SpringBoot集成Swagger2生成接口文檔

原文地址：https://itweknow.cn/detail?id=56 , 歡迎大家訪問掌挚。

我們提供Restful接口的時候已旧，API文檔是尤為的重要策吠，它承載著對接口的定義层皱，描述等伴箩。它還是和API消費方溝通的重要工具识椰。在實際情況中由于接口和文檔存放的位置不同绝葡，我們很難及時的去維護文檔。個人在實際的工作中就遇到過很多接口更新了很久腹鹉，但是文檔卻還是老版本的情況藏畅，其實在這個時候這份文檔就已經(jīng)失去了它存在的意義。而Swagger是目前我見過的最好的API文檔生成工具功咒，使用起來也很方便愉阎，還可以直接調試我們的API。我們今天就來看下Swagger2與SpringBoot的結合力奋。

準備工作

一個SpringBoot項目榜旦，可以直接去官網(wǎng)生成一個demo。
一個用戶類景殷。

package cn.itweknow.springbootswagger.model;

import java.io.Serializable;

/**
 * @author ganchaoyang
 * @date 2018/12/19 10:29
 * @description
 */
public class User implements Serializable {

    private Integer id;

    private String name;

    private String password;

    private String email;
}

項目依賴

Web Service肯定是一個Web項目章办，所以我們這里依賴了spring-boot-starter-web包，其他兩個包就是和Swagger相關的包了滨彻。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Swagger配置

Springfox Docket實例為Swagger配置提供了便捷的配置方法以及合理的默認配置藕届。我們將通過創(chuàng)建一個Docket實例來對Swagger進行配置，具體配置如下所示亭饵。

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                // 掃描的包路徑
                .apis(RequestHandlerSelectors.basePackage("cn.itweknow.springbootswagger.controller"))
                // 定義要生成文檔的Api的url路徑規(guī)則
                .paths(PathSelectors.any())
                .build()
                // 設置swagger-ui.html頁面上的一些元素信息休偶。
                .apiInfo(metaData());
    }

    private ApiInfo metaData() {
        return new ApiInfoBuilder()
                // 標題
                .title("SpringBoot集成Swagger2")
                // 描述
                .description("這是一篇博客演示")
                // 文檔版本
                .version("1.0.0")
                .license("Apache License Version 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

上述代碼中的addResourceHandlers方法添加了兩個資源處理程序，這段代碼的主要作用是對Swagger UI的支持辜羊。

API文檔

好了踏兜，到這一步，我們已經(jīng)在一個SpringBoot項目中配置好了Swagger“送海現(xiàn)在碱妆，我們就來看一下如何去使用他。首先我們定義了一個Controller并提供了兩個接口：

通過用戶id獲取用戶
用戶登錄

@RestController
@RequestMapping("/user")
@Api(description = "用戶相關接口")
public class UserController {

    /**
     * 通過id查詢用戶
     * @return
     */
    @RequestMapping(value = "/get", method = RequestMethod.GET)
    @ApiOperation("根據(jù)id獲取用戶")
    public User getUserById(@ApiParam(value = "用戶id") Integer id) {
        return new User();
    }

    @RequestMapping(value = "/login", method = RequestMethod.POST)
    @ApiOperation("用戶登錄")
    public User login(@RequestBody User user) {
        return new User();
    }
}

相信大家都注意到了昔驱，這個Controller里面多了很多新的注解疹尾，比如說@Api,@ApiOperation等，下面我們就來一一解釋一下。

@Api,這個注解是用在Controller類上面的纳本，可以對Controller做必要的說明窍蓝。
@ApiOperation，作用在具體的方法上繁成，其實就是對一個具體的API的描述吓笙。
@ApiParam，對API參數(shù)的描述巾腕。
到這里面睛，其實我們的Swagger就已經(jīng)可以有效果了，讓我們將項目運行起來先看看效果尊搬。訪問http://localhost:8080/swagger-ui.html即可侮穿。

image

Model

在上面的圖中可以看到在頁面的下方有一個Models的標簽，那么這個是啥呢毁嗦。其實這個就是我們API中出現(xiàn)的一些對象的文檔亲茅，我們也可以通過注解來對這些對象中的字段做一些說明，以方便使用者理解狗准。以文章開頭提到的User類來做一個說明克锣。

@ApiModel("用戶實體")
public class User implements Serializable {

    @ApiModelProperty(value = "用戶id")
    private Integer id;

    @ApiModelProperty(value = "用戶名稱", required = true)
    private String name;

    @ApiModelProperty(value = "密碼", required = true)
    private String password;

    @ApiModelProperty(value = "用戶郵箱")
    private String email;
}

我們來看一下User類在Swagger上是如何展示的：

image

有一個細節(jié)，那就是required = true的字段上面被紅星修飾腔长，代表了必填項袭祟。

API測試

在swagger-ui.html頁面上我們可以直接測試API，如下圖所示捞附，點擊Try it out巾乳，然后填寫參數(shù)，并點擊Execute即可進行調用鸟召。