做java Web的後端開發已經兩年多了，一般都是開發完了接口，都把接口更新到wiki文檔上，然後通知前端去文檔上去查閱接口的詳細描述， 當時經常接口會有變動，加參數或返回值夾字段，所以維護語線上一致的文檔是一件非常麻煩的事情，前一段時間同事聊天說他們公司用的swagger2，這個不需要寫文檔，它是自動生成文檔，只要會使用它提供的幾個的註解就行，於是上網找了下資料，發現它於spring boot集成也非常方便。不廢話直接看了代碼。

　首先，在maven項目的pom.xml加上他需要的依賴。

	        <dependency>
	 		<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.5.0</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.5.0</version>
		</dependency>

　　 然後在Application.class的同一目錄,建立一個類名為Swagger2，類如下：

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(
 
"com.xxx.controller"))
                .paths(PathSelectors.any())
                .build().useDefaultResponseMessages(false);
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("微信API服務").description("wechat service").termsOfServiceUrl("no terms of service")
                .version(
 
"1.0").build();
    }

}

　　 然後，在Swagger2類的同一級建立一個類名為WebMvcConfig類，代碼如下：

@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

這是為了讓 spring boot加載處理swagger的資源的。

然後啟動Application.class啟動spring boot工程，直接訪問http://localhost:8080/swagger-ui.html，就可以出現REST風格的api文檔。

是不是很簡單。

這其中自己也出現過問題，就是我的工程中是在攔截器中做了統一的權限驗證，所以它一直都沒有出現錯誤如下：

調試發現是在token驗證時把Swagger2的訪問頁面的url給攔截了，也花費了自己的一點時間出解決，解決思路是在攔截其中，將url進行特殊判斷，

讓它通過，參考代碼如下：

然後，重啟應用，重新訪問就出現了，在線的 Api文檔就出現了。

　　　　接下來就是熟悉下 swagger2的幾個註解的使用，如下

@Api:註解controller，[email protected]

[email protected]:註解方法，value為簡要描述,notes為全面描述,hidden=true Swagger將不顯示該方法，默認為false

[email protected]:註解參數,hidden=true Swagger參數列表將不顯示該參數,name對應參數名，value為註釋，defaultValue設置默認　　　　　　 值,allowableValues設置範圍值,required設置參數是否必須，默認為false

@ApiModel:註解Model

@ApiModelProperty:註解Model下的屬性，當前端傳過來的是一個對象時swagger中該對象的屬性註解就是ApiModelProperty中的value

@ApiIgnore:註解類、參數、方法，註解後將不在Swagger UI中顯示。

到此借宿，是不是很簡單。大家快去嘗試下吧。　　　　

spring boot集成swagger2