swagger生成接口文檔和map類型參數解析

一：swagger是什麼？

一、是一款讓你更好的書寫API文檔的規範且完整框架。
二、提供描述、生產、消費和可視化RESTful Web Service。
三、是由龐大工具集合支撐的形式化規範。這個集合涵蓋了從終端用戶接口、底層代碼庫到商業API管理的方方面面。html

方法一：使用第三方依賴（最簡單的方法）

一、在pom.xml文件中添加第三方swagger依賴（）git

<dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId>
        <version>1.7.0.RELEASE</version>
    </dependency>

View Code

二、在Spring Boot項目的啓動類上添加@EnableSwagger2Doc註解，就能夠直接使用啦。
三、https://github.com/SpringForAll/spring-boot-starter-swagger這是GitHub上這個swagger依賴實現的項目，裏面有詳細的講解。github

方法二：使用官方依賴

一、在pom.xml文件中添加swagger相關依賴

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox-version}</version>
        </dependency>

View Code

第一個是API獲取的包，第二是官方給出的一個ui界面。這個界面能夠自定義，默認是官方的，對於安全問題，以及ui路由設置須要着重思考。

二、swagger的configuration

須要特別注意的是swagger scan base package,這是掃描註解的配置，即你的API接口位置。spring

@Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("服務:發佈爲daocke鏡像,權限管理，用戶管理，頁面管理，日誌 後臺 APIs") .description("服務:發佈爲daocke鏡像,權限管理，用戶管理，頁面管理，日誌 後臺") .termsOfServiceUrl("http://192.168.103.198:10070/platformgroup/ms-admin") .contact("程序猿DD") .version("1.0") .build(); } }

View Code

3、具體使用

一、在API上作一些聲明

@RequestMapping("/swagger/test/map") @ApiOperation(value="xxxx", tags = "xxxx") @ApiImplicitParams({ @ApiImplicitParam(name="name", dataType = "string", value = "only return models...") }) @ApiResponses(value = { @ApiResponse(code = 200, message="Indicates ..."), @ApiResponse(code = 404, message = "not found error") }) public Result<String> testSwaggerMap(Map map){ return null; }

View Code

https://blog.csdn.net/xtj332/article/details/80595768api

若是項目文檔訪問出現404，參照上面的地址查看緣由安全

https://www.cnblogs.com/mingxiaoyue/p/8877429.htmlapp

若是樣式出現問題請參考上面查看緣由框架

我在實踐中遇到只有swagger頁面頭部的狀況，沒有一個api顯示，通過查證以後發現是shiro安全框架攔截了，將其註釋掉以後就行了。具體緣由尚未肯定，等待有時間查一下，又或許無法解決，反正上線的時候能夠將enable改成false，而後開啓shiro等安全框架的攔截。ide