Spring Boot 2.x基礎教程：使用Swagger2構建強大的API文檔

隨着先後端分離架構和微服務架構的流行，咱們使用Spring Boot來構建RESTful API項目的場景愈來愈多。一般咱們的一個RESTful API就有可能要服務於多個不一樣的開發人員或開發團隊：IOS開發、Android開發、Web開發甚至其餘的後端服務等。爲了減小與其餘團隊平時開發期間的頻繁溝通成本，傳統作法就是建立一份RESTful API文檔來記錄全部接口細節，然而這樣的作法有如下幾個問題：

• 因爲接口衆多，而且細節複雜（須要考慮不一樣的HTTP請求類型、HTTP頭部信息、HTTP請求內容等），高質量地建立這份文檔自己就是件很是吃力的事，下游的抱怨聲不絕於耳。
• 隨着時間推移，不斷修改接口實現的時候都必須同步修改接口文檔，而文檔與代碼又處於兩個不一樣的媒介，除非有嚴格的管理機制，否則很容易致使不一致現象。

爲了解決上面這樣的問題，本文將介紹RESTful API的重磅好夥伴Swagger2，它能夠輕鬆的整合到Spring Boot中，並與Spring MVC程序配合組織出強大RESTful API文檔。它既能夠減小咱們建立文檔的工做量，同時說明內容又整合入實現代碼中，讓維護文檔和修改代碼整合爲一體，可讓咱們在修改代碼邏輯的同時方便的修改文檔說明。另外Swagger2也提供了強大的頁面測試功能來調試每一個RESTful API。具體效果以下圖所示：

下面來具體介紹，在Spring Boot中使用咱們本身實現的starter來整合Swagger。該整合項目的Github：https://github.com/SpringForAll/spring-boot-starter-swagger。若是您以爲它好用，歡迎Star支持咱們！

準備工做

首先，咱們須要一個Spring Boot實現的RESTful API工程，若您沒有作過這類內容，建議先閱讀上一篇教程：
Spring Boot 2.x基礎教程：構建RESTful API與單元測試構建一個。或者也能夠直接使用上一篇教程中的樣例做爲基礎，即下面倉庫中的chapter2-1工程：

• Github：https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
• Gitee：https://gitee.com/didispace/SpringBoot-Learning/tree/2.x

整合Swagger2

下面，咱們以上面倉庫中的chapter2-1工程進行整合改造。

第一步：添加swagger-spring-boot-starter依賴

在pom.xml中加入依賴，具體以下：

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

第二步：應用主類中添加@EnableSwagger2Doc註解，具體以下

@EnableSwagger2Doc
@SpringBootApplication
public class Chapter22Application {

    public static void main(String[] args) {
        SpringApplication.run(Chapter22Application.class, args);
    }

}

第三步：application.properties中配置文檔相關內容，好比

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.4.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=didi
swagger.contact.url=http://blog.didispace.com
swagger.contact.email=dyc87112@qq.com
swagger.base-package=com.didispace
swagger.base-path=/**

各參數配置含義以下：

• swagger.title：標題
• swagger.description：描述
• swagger.version：版本
• swagger.license：許可證
• swagger.licenseUrl：許可證URL
• swagger.termsOfServiceUrl：服務條款URL
• swagger.contact.name：維護人
• swagger.contact.url：維護人URL
• swagger.contact.email：維護人email
• swagger.base-package：swagger掃描的基礎包，默認：全掃描
• swagger.base-path：須要處理的基礎URL規則，默認：/**

更多配置說明可見官方說明：https://github.com/SpringForAll/spring-boot-starter-swagger

第四步：啓動應用，訪問：http://localhost:8080/swagger-ui.html，就能夠看到以下的接口文檔頁面：

添加文檔內容

在整合完Swagger以後，在http://localhost:8080/swagger-ui.html頁面中能夠看到，關於各個接口的描述還都是英文或遵循代碼定義的名稱產生的。這些內容對用戶並不友好，因此咱們須要本身增長一些說明來豐富文檔內容。以下所示，咱們經過@Api，@ApiOperation註解來給API增長說明、經過@ApiImplicitParam、@ApiModel、@ApiModelProperty註解來給參數增長說明。

好比下面的例子：

@Api(tags = "用戶管理")
@RestController
@RequestMapping(value = "/users")     // 經過這裏配置使下面的映射都在/users下
public class UserController {

    // 建立線程安全的Map，模擬users信息的存儲
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());

    @GetMapping("/")
    @ApiOperation(value = "獲取用戶列表")
    public List<User> getUserList() {
        List<User> r = new ArrayList<>(users.values());
        return r;
    }

    @PostMapping("/")
    @ApiOperation(value = "建立用戶", notes = "根據User對象建立用戶")
    public String postUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "獲取用戶詳細信息", notes = "根據url的id來獲取用戶詳細信息")
    public User getUser(@PathVariable Long id) {
        return users.get(id);
    }

    @PutMapping("/{id}")
    @ApiImplicitParam(paramType = "path", dataType = "Long", name = "id", value = "用戶編號", required = true, example = "1")
    @ApiOperation(value = "更新用戶詳細信息", notes = "根據url的id來指定更新對象，並根據傳過來的user信息來更新用戶詳細信息")
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "刪除用戶", notes = "根據url的id來指定刪除對象")
    public String deleteUser(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }

}

@Data
@ApiModel(description="用戶實體")
public class User {

    @ApiModelProperty("用戶編號")
    private Long id;
    @ApiModelProperty("用戶姓名")
    private String name;
    @ApiModelProperty("用戶年齡")
    private Integer age;

}

完成上述代碼添加後，啓動Spring Boot程序，訪問：http://localhost:8080/swagger-ui.html，就能看到下面這樣帶中文說明的文檔了（其中標出了各個註解與文檔元素的對應關係以供參考）：

API文檔訪問與調試

在上圖請求的頁面中，咱們看到user的Value是個輸入框？是的，Swagger除了查看接口功能外，還提供了調試測試功能，咱們能夠點擊上圖中右側的Model Schema（黃色區域：它指明瞭User的數據結構），此時Value中就有了user對象的模板，咱們只須要稍適修改，點擊下方「Try it out！」按鈕，便可完成了一次請求調用！

此時，你也能夠經過幾個GET請求來驗證以前的POST請求是否正確。

相比爲這些接口編寫文檔的工做，咱們增長的配置內容是很是少並且精簡的，對於原有代碼的侵入也在忍受範圍以內。所以，在構建RESTful API的同時，加入Swagger來對API文檔進行管理，是個不錯的選擇。

代碼示例

本文的完整工程能夠查看下面倉庫中的chapter2-2目錄：

• Github：https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
• Gitee：https://gitee.com/didispace/SpringBoot-Learning/tree/2.x

若是您以爲本文不錯，歡迎Star支持，您的關注是我堅持的動力！

歡迎關注個人公衆號：程序猿DD，得到獨家整理的學習資源和平常乾貨推送。若是您對個人專題內容感興趣，也能夠關注個人博客：didispace.com