在項(xiàng)目開(kāi)發(fā)中，一般都是由前后端工程師共同定義接口，編寫(xiě)接口文檔，之后大家根據(jù)這個(gè)接口文檔進(jìn)行開(kāi)發(fā)、維護(hù)。為了便于編寫(xiě)和維護(hù)穩(wěn)定，可以使用 Swagger 來(lái)編寫(xiě) API 接口文檔，以提升團(tuán)隊(duì)的溝通效率。

下面演示如何在 Spring Boot 中繼承 Swagger。

1.配置 Swagger

1.1 添加 Swagger 依賴(lài)

<!--Swagger依賴(lài)-->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency><!--Swagger-UI依賴(lài) -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>

1.2 創(chuàng)建 Swagger 配置類(lèi)

創(chuàng)建 Swagger 配置類(lèi)，完成相關(guān)配置項(xiàng)，見(jiàn)以下代碼：

package com.example.demo.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;/*** Swagger 配置類(lèi)* 在與 Spring Boot 集成時(shí)，放在與 Application.java 同級(jí)的目錄下*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {/*** 創(chuàng)建 API 應(yīng)用* 本例采用指定掃描的包路徑來(lái)定義指定要建立 API 的目錄*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build();}/*** 創(chuàng)建該 API 的基本信息（這些基本信息會(huì)展現(xiàn)在文檔頁(yè)面中）* 訪問(wèn)地址：http://項(xiàng)目實(shí)際地址/swagger-ui.html*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title(" RESTful APIs").description("RESTful APIs").termsOfServiceUrl("http://localhost:8080/").contact("pipi").version("1.0").build();}
}

• @Configuration：讓 Spring 來(lái)加載該類(lèi)配置。
• @EnableSwagger2：啟用 Swagger2.createRestApi 函數(shù)創(chuàng)建 Docket 的 Bean。
• apiInfo()：用來(lái)展示該 API 的基本信息。
• select()：返回一個(gè) ApiSelectorBuilder 實(shí)例，用來(lái)控制哪些接口暴露給 Swagger 來(lái)展現(xiàn)。
• apis(RequestHandlerSelectors.basePackage())：配置包掃描路徑。Swagger 會(huì)掃描包下所有 Controler 定義的 API，并產(chǎn)生文檔內(nèi)容。如果不想產(chǎn)生 API，則使用注解 @ApiIgnore。

2.編寫(xiě)接口文檔

在完成上述配置后，即生成了文檔，但是這樣生成的文檔主要針對(duì)請(qǐng)求本身，而描述自動(dòng)根據(jù)方法等命名產(chǎn)生，對(duì)用戶并不友好。所以，通常需要自己增加一些說(shuō)明以豐富文檔內(nèi)容?？梢酝ㄟ^(guò)以下注解來(lái)增加說(shuō)明。

• @Api：描述類(lèi)/接口的主要用途。
• @ApiOperation：描述方法用途，給 API 增加說(shuō)明。
• @ApiImplicitParam：描述方法的參數(shù)，給參數(shù)增加說(shuō)明。
• @ApiImplicitParams：描述方法的參數(shù)（Multi-Params），給參數(shù)增加說(shuō)明。
• @ApiIgnore：忽略某類(lèi)/方法/參數(shù)的文檔。

具體使用方法見(jiàn)以下代碼：

package com.example.demo.controller;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;@RestController
public class HelloWorldController {@ApiOperation(value = "hello", notes = "notes")@RequestMapping("/hello")public String hello() throws Exception {return "HelloWorld ,Spring Boot!";}// 使用該注解忽略這個(gè) API@ApiIgnore@RequestMapping(value = "/ignoreApi")public String  ignoreApi() {return "HelloWorld ,Spring Boot!";}
}

完成上述代碼后，啟動(dòng)項(xiàng)目，訪問(wèn) http://localhost:8080/swagger-ui.html 就能看到所展示的 RESTful API 的頁(yè)面，可以通過(guò)單擊具體的 API 測(cè)試請(qǐng)求，來(lái)查看代碼中配置的信息，以及參數(shù)的描述信息。