Spring Boot API 接口文檔 Swagger 入門（上）

• 1. 概述
• 2. 快速入門 Swagger
• 3. 更好看的 Swagger UI 界面
• 4. 更強大的 YApi
• • *

1. 概述

目前，大多數系統都採用先後端分離。在享受先後端分離的好處的同時，接口聯調每每成爲團隊效率的瓶頸，甚至產生先後端的矛盾。簡單歸結來講，有幾方面的緣由：

• 問題一，接口設計滯後。 後端團隊每每不喜歡 API 接口設計先行，提早和前端溝通好接口。而在開發階段的中後期，在後端提供 API 接口後，而這些接口和前端的預期有一些誤差，很容易就產生抱怨，特別是項目週期比較緊張的狀況下。
• 問題二，接口不規範。 當團隊裏沒有贊成明確的接口規範時，又或者代碼 Review 作的不是很好的狀況下，千奇百怪、各式各樣的 API 接口可能就產生了。前端在對接這樣的 API 接口，苦不堪言，在一口 mmp 一嘴 fuck xxx 之中，調完接口。
• 問題三，接口文檔更新不及時，或者遺忘更新。 由於後端 API 代碼和 API 接口在兩個地方，咱們沒法保證提交 API 代碼的同時，及時更新文檔。有的時候，咱們甚至會遺忘更新 API 接口。隨着時間的流逝，API 文檔和 API 接口不一致的地方愈來愈多，前端會對 API 接口的信任度愈來愈低，而後不知道不覺之中，回到原始時代，直接問後端開發 API 是什麼樣的。

對於問題一和問題二，更可能是開發流程上的問題，因此不在本文的範圍內。固然話癆的艿艿，仍是要給點粗淺的建議，徹底攔不住我啊。

• 接口設計先行。設計完成後，後端和前端進行簡單溝通，看看是否可以知足訴求。
• 統一的接口規範。必定要制定統一的接口規範文檔，即便比較簡陋，也能保證團隊的 API 接口相對統一一致。 即便錯，咱也錯的如出一轍，而不是千奇百怪。固然，接口規範是沒法覆蓋到全部的場景的，藉助於「接口設計先行」，咱們能夠提早去 Review 每一個接口的設計。

對於問題三，就進入了本文的主角 Swagger 。經過在 API 接口上，添加相應的 Swagger 提供的註解，自動生成 API 文檔。醬紫，API 接口和文檔就在一塊兒了，今後過上了幸福快樂的生活。

FROM 《RESTful 風格的 Web 服務框架 Swagger》

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。

整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法、參數和模型緊密集成到服務器端的代碼，容許 API 來始終保持同步。Swagger 讓部署管理和使用功能強大的 API 從未如此簡單。

預覽圖

2. 快速入門 Swagger

示例代碼對應倉庫：lab-24-apidoc-swagger 。

在本小節，咱們來快速入門 Swagger ，能夠更加直觀的感覺到其提供的便利性。

2.1 引入依賴

在 pom.xml 文件中，引入相關依賴。

<?xml version="1.0" encoding="UTF-8"?><project xmlns="http://maven.apache.org/POM/4.0.0"         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">    <parent>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-parent</artifactId>        <version>2.1.3.RELEASE</version>        <relativePath/> <!-- lookup parent from repository -->    </parent>    <modelVersion>4.0.0</modelVersion>    <artifactId>lab-24-apidoc-swagger</artifactId>    <dependencies>        <!-- 實現對 Spring MVC 的自動化配置 -->        <dependency>            <groupId>org.springframework.boot</groupId>            <artifactId>spring-boot-starter-web</artifactId>        </dependency>        <!-- 引入 Swagger 依賴 -->        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger2</artifactId>            <version>2.9.2</version>        </dependency>        <!-- 引入 Swagger UI 依賴，以實現 API 接口的 UI 界面 -->        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger-ui</artifactId>            <version>2.9.2</version>        </dependency>    </dependencies></project>

具體每一個依賴的做用，胖友本身認真看下艿艿添加的全部註釋噢。

2.2 SwaggerConfiguration

由於 Spring Boot 暫未提供 Swagger 內置的支持，因此咱們須要本身定義配置類。

在 cn.iocoder.springboot.lab24.apidoc.config 包路徑下，建立 SwaggerConfiguration 配置類，用於配置 Swagger 。代碼以下：

// SwaggerConfiguration.java@Configuration@EnableSwagger2 // 標記項目啓用 Swagger API 接口文檔public class SwaggerConfiguration {    @Bean    public Docket createRestApi() {        // 建立 Docket 對象        return new Docket(DocumentationType.SWAGGER_2) // 文檔類型，使用 Swagger2                .apiInfo(this.apiInfo()) // 設置 API 信息                // 掃描 Controller 包路徑，得到 API 接口                .select()                .apis(RequestHandlerSelectors.basePackage("cn.iocoder.springboot.lab24.apidoc.controller"))                .paths(PathSelectors.any())                // 構建出 Docket 對象                .build();    }    /**     * 建立 API 信息     */    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("測試接口文檔示例")                .description("我是一段描述")                .version("1.0.0") // 版本號                .contact(new Contact("芋艿", "http://www.iocoder.cn", "zhijiantianya@gmail.com")) // 聯繫人                .build();    }}

• 在類上，添加 @EnableSwagger2 註解， 標記項目啓用 Swagger API 接口文檔。
• 經過 #createRestApi() 方法，建立 Swagger Docket Bean 。每一個屬性的做用，胖友看看艿艿的註釋。大多數狀況下，胖友使用這些屬性是足夠的。不過若是想看看其它配置，胖友能夠本身去以下兩個類翻翻：
• Docket.java
• ApiInfo.java

2.3 Application

建立 Application.java 類，配置 @SpringBootApplication 註解便可。代碼以下：

// Application.java@SpringBootApplicationpublic class Application {    public static void main(String[] args) {        SpringApplication.run(Application.class, args);    }}

先暫時不啓動項目。等咱們添加好 Controller 。

2.4 UserController

在 cn.iocoder.springboot.lab24.apidoc.controller 包路徑下，建立 UserController 類，提供用戶 API 接口。代碼以下：

// UserController.java@RestController@RequestMapping("/users")@Api(tags = "用戶 API 接口")public class UserController {    @GetMapping("/list")    @ApiOperation(value = "查詢用戶列表", notes = "目前僅僅是做爲測試，因此返回用戶全列表")    public List<UserVO> list() {        // 查詢列表        List<UserVO> result = new ArrayList<>();        result.add(new UserVO().setId(1).setUsername("yudaoyuanma"));        result.add(new UserVO().setId(2).setUsername("woshiyutou"));        result.add(new UserVO().setId(3).setUsername("chifanshuijiao"));        // 返回列表        return result;    }    @GetMapping("/get")    @ApiOperation("得到指定用戶編號的用戶")    @ApiImplicitParam(name = "id", value = "用戶編號", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")    public UserVO get(@RequestParam("id") Integer id) {        // 查詢並返回用戶        return new UserVO().setId(id).setUsername(UUID.randomUUID().toString());    }    @PostMapping("add")    @ApiOperation("添加用戶")    public Integer add(UserAddDTO addDTO) {        // 插入用戶記錄，返回編號        Integer returnId = UUID.randomUUID().hashCode();        // 返回用戶編號        return returnId;    }    @PostMapping("/update")    @ApiOperation("更新指定用戶編號的用戶")    public Boolean update(UserUpdateDTO updateDTO) {        // 更新用戶記錄        Boolean success = true;        // 返回更新是否成功        return success;    }    @PostMapping("/delete")    @ApiOperation(value = "刪除指定用戶編號的用戶")    @ApiImplicitParam(name = "id", value = "用戶編號", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")    public Boolean delete(@RequestParam("id") Integer id) {        // 刪除用戶記錄        Boolean success = false;        // 返回是否更新成功        return success;    }}

• 相比咱們以前使用 SpringMVC 來講，咱們在類和接口上，額外增長了 Swagger 提供的註解。
• 從使用習慣上，我比較喜歡先添加 SpringMVC 的註解，再添加 Swagger 的註解。
• 由於已經使用了 Swagger 的註解，因此類和方法上的註釋，通常能夠刪除了，除非有特殊訴求。
• 其中涉及到的 POJO 類，有 UserAddDTO、UserUpdateDTO、UserVO 。

執行 Application 啓動項目。而後瀏覽器訪問 http://127.0.0.1:8080/swagger-ui.html地址，就能夠看到 Swagger 生成的 API 接口文檔。以下圖所示：

至此，咱們已經完成了 Swagger 的快速入門。不過考慮到胖友可以更好的使用，咱們來一個一個註解瞭解。

2.5 註解

在 swagger-annotations 庫中，在 io.swagger.annotations 包路徑下，提供了咱們會使用到的全部 Swagger 註解。Swagger 提供的註解仍是比較多的，大多數場景下，只須要使用到咱們在 「2.4 UserController」 中用到的註解。

2.5.1 @Api

@Api 註解，添加在 Controller 類上，標記它做爲 Swagger 文檔資源。

示例以下：

// UserController.java@RestController@RequestMapping("/users")@Api(tags = "用戶 API 接口")public class UserController {    // ... 省略}

效果以下：

@Api 註解的經常使用屬性，以下：

• tags 屬性：用於控制 API 所屬的標籤列表。[] 數組，能夠填寫多個。
• 能夠在一個 Controller 上的 @Api 的 tags 屬性，設置多個標籤，那麼這個 Controller 下的 API 接口，就會出如今這兩個標籤中。
• 若是在多個 Controller 上的 @Api 的 tags 屬性，設置一個標籤，那麼這些 Controller 下的 API 接口，僅會出如今這一個標籤中。
• 本質上，tags 就是爲了分組 API 接口，和 Controller 本質上是一個目的。因此絕大數場景下，咱們只會給一個 Controller 一個惟一的標籤。例如說，UserController 的 tags 設置爲 "用戶 API 接口" 。

@Api 註解的不經常使用屬性，以下：

• produces 屬性：請求請求頭的可接受類型( Accept )。若是有多個，使用 , 分隔。
• consumes 屬性：請求請求頭的提交內容類型( Content-Type )。若是有多個，使用 ,分隔。
• protocols 屬性：協議，可選值爲 "http"、"https"、"ws"、"wss" 。若是有多個，使用 , 分隔。
• authorizations 屬性：受權相關的配置，[] 數組，使用 @Authorization 註解。
• hidden 屬性：是否隱藏，再也不 API 接口文檔中顯示。

@Api 註解的廢棄屬性，不建議使用，有value、description、basePath、position 。

2.5.2 @ApiOperation

@ApiOperation 註解，添加在 Controller 方法上，標記它是一個 API 操做。

示例以下：

// UserController.java@GetMapping("/list")@ApiOperation(value = "查詢用戶列表", notes = "目前僅僅是做爲測試，因此返回用戶全列表")public List<UserVO> list() {    // 查詢列表    List<UserVO> result = new ArrayList<>();    result.add(new UserVO().setId(1).setUsername("yudaoyuanma"));    result.add(new UserVO().setId(2).setUsername("woshiyutou"));    result.add(new UserVO().setId(3).setUsername("chifanshuijiao"));    // 返回列表    return result;}

效果以下：

@ApiOperation 註解的經常使用屬性，以下：

• value 屬性：API 操做名。
• notes 屬性：API 操做的描述。

@ApiOperation 註解的不經常使用屬性，以下：

• tags 屬性：和 @API 註解的 tags 屬性一致。
• nickname 屬性：API 操做接口的惟一標識，主要用於和第三方工具作對接。
• httpMethod 屬性：請求方法，可選值爲 GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH 。由於 Swagger 會解析 SpringMVC 的註解，因此通常無需填寫。
• produces 屬性：和 @API 註解的 produces 屬性一致。
• consumes 屬性：和 @API 註解的 consumes 屬性一致。
• protocols 屬性：和 @API 註解的 protocols 屬性一致。
• authorizations 屬性：和 @API 註解的 authorizations 屬性一致。
• hidden 屬性：和 @API 註解的 hidden 屬性一致。
• response 屬性：響應結果類型。由於 Swagger 會解析方法的返回類型，因此通常無需填寫。
• responseContainer 屬性：響應結果的容器，可選值爲 List、Set、Map 。
• responseReference 屬性：指定對響應類型的引用。這個引用能夠是本地，也能夠是遠程。而且，當設置了它時，會覆蓋 response 屬性。說人話，就是能夠忽略這個屬性，哈哈哈。
• responseHeaders 屬性：響應頭，[] 數組，使用 @ResponseHeader 註解。
• code 屬性：響應狀態碼，默認爲 200 。
• extensions 屬性：拓展屬性，[] 屬性，使用 @Extension 註解。
• ignoreJsonView 屬性：在解析操做和類型，忽略 JsonView 註釋。主要是爲了向後兼容。

@ApiOperation 註解的廢棄屬性，不建議使用，有 position 。