springMVC項目中引入swagger2，展現RESTful API

1. 爲何用swagger2？swagger1和2試用對比

2. 在springMVC項目中引入swagger2

3. springfox與swagger的關係

4. 對第2步配置的說明

---

 1.爲何用swagger2?swagger1和2試用對比

試用過swagger-springmvc和springfox-swagger2後，爲了能限定暴露哪些接口，選用swagger2。

1. swagger2的引入更加輕量化：依賴關係+swagger2配置文件+@Api註解搞定，沒必要像swagger-springmvc還須要單獨引入頁面顯示包。
2. 經過swagger2提供的Docket類，能夠更多的控制api文檔的生成。

 

---

2.在springMVC項目中引入swagger2

1.配置依賴關係

pom.xml

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

 注：沒必要引入jackson-core, jackson-databind，會形成tomcat啓動報錯：

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is com.google.common.util.concurrent.ExecutionError: com.google.common.util.concurrent.ExecutionError: java.lang.NoClassDefFoundError: com/fasterxml/jackson/annotation/JsonProperty$Access

緣由：pom有最近多餘添加的的依賴，刪除便可。

 

2.配置Swagger2Congig類

@Configuration @EnableSwagger2 @EnableWebMvc @ComponentScan(basePackages = {"cn.com.sinosure.appApi.controller"}) public class Swagger2Config extends WebMvcConfigurerAdapter { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() // 選擇那些路徑和api會生成document
                .paths(Predicates.not(PathSelectors.regex("/error.*"))) .apis(RequestHandlerSelectors.basePackage("cn.com.xx.packageName"))  // 根據包名選擇 //.apis(RequestHandlerSelectors.any()) // 對全部api進行監控
                .paths(PathSelectors.any())  // 對全部路徑進行監控
 .build() .apiInfo(apiInfo()); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API文檔") .description("springfox-swagger2") .termsOfServiceUrl("") .version("1.0") .build(); } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { //enabling swagger-ui part for visual documentation
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); } }

 注：自定義的swagger2配置類應在<context:component-scan>配置的base-package路徑下，不然會形成訪問 http://localhost:8080/<projectName>/swagger-ui.html 除swagger圖標正常顯示外，其餘空白。

 

3.寫一個Test類（試用）

@Controller @RequestMapping("/test") public class Test { @ApiOperation(value = "一個測試API", notes = "第一個測試api") @ResponseBody @RequestMapping(value = "/hello", method = RequestMethod.GET) public String hello() { return "hello"; } }

 

4.http://localhost:8080/swagger-ui.html

 

---

3.springfox與swagger的關係

Swagger API開發框架，基於OAS（OpenAPI Specification，一個API規範，規範RESTful服務開發過程；描述API接口，採用YAML格式/json格式）。

初代：基於Spring的組件：swagger-springmvc

後發展爲springfox，其中的一個組件springfox-swagger2，能夠自動生成符合OAS規範的json文件；另外一個組件springfox-swagger-ui負責解析此json文件，以友好的界面形式展示。

 

---

 4.對第2步配置的說明

任務拆解

• 一個spring項目，引入swagger2。
• 生成一個符合OAS規範的json文件。前文已提到springfox-swagger2可自動生成此json文件，但須要咱們在項目中作一些配置：對swagger的配置主要圍繞Docket類，做爲一個bean注入spring中。經過這個配置文件，咱們能夠：

選擇哪些路徑和api會暴露出來；

將API描述信息封裝到apiInfo類中，做爲參數傳給Docket；

全局覆寫HTTP方法的返回信息。

• 控制器，經過註解的方式，告訴springfox，這個控制器須要他來收集API信息。

驗收

• json文檔

http://localhost:8080/<projectName>/v2/api-docs

• 可視化顯示

在swagger-springmvc組件中，須要單獨引用swagger-ui的頁面顯示包（把dist目錄下的內容拷到項目中WEB-INF目錄下）。

而使用升級後的springfox-swagger2，只須要添加對springfox-swagger-ui的依賴。

http://localhost:8080/<projextName>/swagger-ui.html

 

---

5.參考：

Springfox與swagger的整合使用

Setting Up Swagger 2 with a Spring REST API

springfox-swagger原理解析與使用過程當中遇到的坑

swagger-springmvc:Restful形式接口文檔生成之Swagger與SpringMVC整合手記