知識改變命運，擼碼使我快樂，你的發跡線還好嗎？
點贊再看，養成習慣
本篇文章對應源碼碼云（Gitee）倉庫
https://gitee.com/minbox-projects/api-boot-chapter，您的Star是給我最大動力
接口文檔在前后分離的項目中是必不可少的一部分，文檔的編寫一直以來都是一件頭疼的事情，寫程序不寫注釋、不寫文檔這幾乎是程序員的通病，Swagger2的產生給廣大的程序員們帶來了曙光，只需要在接口類或者接口的方法上添加注解配置，就可以實現文檔效果，除了可以應用到單體應用，在微服務架構中也是可以使用的，只需要整合zuul就可以實現各個服務的文檔整合。
本文所需ApiBoot相關鏈接：
前言
ApiBoot Swagger內部封裝了Swagger2，只需要一個注解@EnableApiBootSwagger就可以實現集成，使用起來非常簡單。
ApiBoot Swagger提供了一系列的默認配置，比如：文檔標題、文檔描述、文檔版本號等，如果需要修改文檔的默認配置，只需要在application.yml文件內對應配置參數即可實現自定義，告別了繁瑣的代碼配置，ApiBoot通過自動化配置的方式來實現這一點，可以查看 ApiBootSwaggerAutoConfiguration 配置類源碼了解詳情。
ApiBoot Swagger支持在線調試集成OAuth2的接口，只需要在文檔界面通過 "Authorize"按鈕設置有效的AccessToken即可。
可配置參數一覽
ApiBoot Swagger之所以可以只需要一個注解就可以實現Swagger2的集成，其中難免有很多的配置參數在做支持，了解每一個配置參數的作用，我們才能進行心應手的自定義調整。
| 參數名 | 默認值 | 描述 |
|---|---|---|
| api.boot.swagger.enable | true | 是否啟用文檔 |
| api.boot.swagger.title | ApiBoot快速集成Swagger文檔 | 文檔標題 |
| api.boot.swagger.description | - | 文檔描述 |
| api.boot.swagger.base-package | SpringBoot默認package，詳見AutoConfigurationPackages
|
生成文檔的基礎package |
| api.boot.swagger.version | ApiBoot的版本號 | 文檔版本號 |
| api.boot.swagger.authorization.name | 授權名稱 | |
| api.boot.swagger.authorization.key-name | Authorization | 整合Oauth2后AccessToken在Header內的Name |
上面是常用的參數，更多配置參數詳見官方文檔：http://apiboot.minbox.io/zh-cn/docs/api-boot-swagger.html
創建示例項目
我們先來創建一個SpringBoot應用程序，在項目的pom.xml文件內添加ApiBoot的相關依賴，如下所示：
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.minbox.framework</groupId>
<artifactId>api-boot-starter-swagger</artifactId>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.minbox.framework</groupId>
<artifactId>api-boot-dependencies</artifactId>
<version>2.2.1.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
啟用ApiBoot Swagger
通過@EnableApiBootSwagger注解來啟用ApiBoot Swagger，該注解可以配置在XxxApplication入口類上，也可以配置在被@Configuration注解修飾的配置類上。
@SpringBootApplication
@EnableApiBootSwagger
public class ApibootSwaggerDescribeTheInterfaceApplication {
public static void main(String[] args) {
SpringApplication.run(ApibootSwaggerDescribeTheInterfaceApplication.class, args);
}
}
修改默認配置
ApiBoot Swagger所提供的配置參數都可以在application.yml文件內進行設置或修改默認值，下面是修改了版本號、標題的配置：
# ApiBoot相關配置
api:
boot:
swagger:
# 配置文檔標題
title: 接口文檔
# 配置文檔版本
version: v1.0
測試控制器
為了方便演示Swagger文檔的強大之處，我們來創建一個測試的控制器，使用Swagger提供的注解來描述測試接口，如下所示：
/**
* 示例控制器
*
* @author 恒宇少年
*/
@RestController
@RequestMapping(value = "/user")
@Api(tags = "用戶控制器")
public class UserController {
/**
* 示例：
* 根據用戶名查詢用戶基本信息
*
* @param name {@link UserResponse#getName()}
* @return {@link UserResponse}
*/
@GetMapping(value = "/{name}")
@ApiOperation(value = "查詢用戶信息", response = UserResponse.class)
@ApiResponse(code = 200, message = "success", response = UserResponse.class)
public UserResponse getUser(@PathVariable("name") String name) {
return new UserResponse(name, 25);
}
/**
* 響應實體示例
*/
@ApiModel
@Data
@AllArgsConstructor
@NoArgsConstructor
public static class UserResponse {
@ApiModelProperty(value = "用戶名")
private String name;
@ApiModelProperty(value = "年齡")
private Integer age;
}
}
注意：
ApiBoot Swagger只是針對Swagger進行了封裝，實現了快速集成，對內部的注解以及配置不做修改。
運行測試
啟動本章項目源碼，訪問：http://localhost:8080/swagger-ui.html 查看運行效果，如下圖所示：
當我們點擊 "用戶控制器" 時可以展開該Controller內定義的接口列表，每一個接口都提供了 "Try it out"（在線調試）功能。
本章并沒有集成
OAuth2，在執行在線調試時并不需要配置AccessToken。
敲黑板，劃重點
ApiBoot Swagger的實現主要歸功于SpringBoot自定義Starter，根據配置參數進行條件配置控制對象的實例化，通過@Import來導入Swagger所需要的配置類。
代碼示例
如果您喜歡本篇文章請為源碼倉庫點個Star，謝謝！！！
本篇文章示例源碼可以通過以下途徑獲取，目錄為apiboot-swagger-describe-the-interface：
