在現在的開發過程中，基本上已經全部採用API 介面的方式進行系統的開發了，於是乎，在此過程中，一個好的API 文件便成為了後台與前台進行溝通與開發的關鍵橋樑。
傳統的做法是由開發人員創建一份RESTful API 文件來記錄所有的介面細節，說實話，這樣的工作量並不小，而且十分瑣碎，且隨著專案的更新會出現以下問題。
文件難以維護。
介面內容更複雜，寫效率更低。
Swagger 便是為了解決這個問題，它作為一個規格和完整的框架，可以用來產生、描述、呼叫和視覺化RESTful 風格的Web 服務：
透過Swagger，我們可以在開發介面的過程中透過使用註解自動產生/更新API 介面文檔，且在文檔頁面支援介面的偵錯。
接下來就簡單說一下，如何在SpringBoot 中整合Swagger2(2 代表其版本)
pom.xml 文件
<dependencies>
<!--Swagger2 在此，个人推荐使用2.8.0版本，较为稳定-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
</dependencies>Swagger2Config.java java 設定檔
@Configuration
// 指定扫描的api包路径
@ComponentScan(basePackages = {"cn.beatree.xxx.controller"})
//注解开启 swagger2 功能
@EnableSwagger2
public class Swagger2Config {
@Value("${swagger2.enable}")
boolean enable;
// 配置文件中通过值注入控制生产环境与开发环境下的启用状态
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.enable(enable)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("ANONVOTE | Swagger API文档")//标题
.description("description: ANONVOTE | Swagger API文档")//描述
.contact("BEATREE")//作者信息
.version("1.0.0")//版本号
.build();
}
}application.yml 設定檔
swagger2: enable: false #true 启用
@Configuration 註解，指定為配置類，會在SpringBoot 啟動時進行載入。
@EnableSwagger2 註解來啟用 Swagger2。
成員方法 createRestApi 函數建立 Docket 的 Bean 之後，apiInfo() 用來創建該 Api 的基本資訊（這些基本資訊會展現在文件頁面中）。 select() 函數傳回一個 ApiSelectorBuilder 實例用來控制哪些介面暴露給 Swagger 來展現，本例採用指定掃描的套件路徑來定義，Swagger 會掃描該套件下所有 Controller 定義的 API，並產生文件內容（除了被 @ApiIgnore 指定的請求）。
常用Swagger 註解
@Api：修飾整個類，描述Controller 的作用
@ApiOperation：描述一個類別的一個方法，或者說一個介面
@ApiParam：單一參數描述@ApiModel：用物件來接收參數
@ApiProperty：用物件接收參數時，描述物件的一個欄位
@ApiResponse：HTTP 回應其中1 個描述
@ApiResponses：HTTP 回應整體描述
@ApiIgnore ：使用該註解忽略這個API
@ApiError ：發生錯誤回傳的訊息
@ApiImplicitParam：描述一個請求參數，可以配置參數的中文意義，也可以為參數設定預設值
@ApiImplicitParams：描述由多個
@ApiImplicitParam# 註解的參數所組成的請求參數清單
舉個栗子
@RestController
@Transactional // 事务注解，实现回滚
@RequestMapping("/api/tlink")
@Api(value = "/api/tlink", tags = "参与者相关接口")
public class TlinkController{
@GetMapping("/checkCode/{code}")
@ApiOperation(value = "投票认证码核验接口",
notes = "该接口用于核验认证码合法性，对于投票主题内容的获取需后续调用Topic相关接口。返回值data中带有参数 topic & options")
public JSONObject checkCode(@PathVariable("code") String code){
...
}
}最後在執行SpringBoot 專案之後，透過伺服器位址/swagger-ui.html 存取即可。
要注意的是，如已新增路徑攔截器，需透過
.excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**")對 swagger 路徑放行。
以上是SpringBoot整合Swagger2產生介面文檔，媽媽再也不用擔心我寫API文檔了的詳細內容。更多資訊請關注PHP中文網其他相關文章！
