背景

在前后端分離開發(fā)中，為了減少與其它團隊的溝通成本，一般都會構(gòu)建一份 RESTful API 文檔來描述所有的接口信息。但傳統(tǒng)的方式有許多弊端，不僅編寫文檔工作量巨大，而且維護不方便，測試也不方便（需要借助第三方工具，如 Postman 來測試）

為解決這些問題，我們可以使用 Swagger 2 來構(gòu)建在線接口文檔，把代碼和文檔融為一體，減少人工維護文檔的成本

目標

學習在Springboot項目中集成Swagger在線文檔

內(nèi)容

安裝配置

1. 首先編輯項目的 pom.xml 文件，添加 Swagger 2 相關依賴

2.創(chuàng)建 Swagger 2 的配置類，代碼如下

使用示例

1. 首先我們在 Controller 上添加相關的 @Api 注解

（1）@Api 注解標注在類上用來描述整個 Controller 信息。
（2）@ApiOperation 注解標注在方法上，用來描述一個方法的基本信息。
（3）@ApiImplicitParam 注解標注在方法上，用來描述方法的參數(shù)。其中 paramType 是指方法參數(shù)的類型，有如下可選值：

• path：參數(shù)獲取方式為 @PathVariable

• query：參數(shù)獲取方式為 @RequestParam

• header：參數(shù)獲取方式為 @RequestHeader

• body

• form

（4）如果有多個參數(shù)，可以將多個參數(shù)的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中。
（5）@ApiResponse 是對響應結(jié)果的描述。code 表示響應碼，message 為相應的描述信息。如果有多個 @ApiResponse，則放在一個 @ApiResponses 中。
（6）@ApiIgnore 注解表示不對某個接口生成文檔。

2.對模型對象也添加相關的注解

查看接口文檔

1. 啟動 Spring Boot 項目，在瀏覽器中輸入 http://localhost:8080/swagger-ui.html 即可看到接口文檔

2.點擊任一接口，可以進行測試