二十三察郁、Spring Boot使用Swagger2生成API文檔

一、Swagger2概念

Swagger 是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件驻呐。

Swagger 是一個規(guī)范和完整的框架灌诅，用于生成、描述含末、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)猜拾。總體目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新佣盒。文件的方法挎袜，參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API來始終保持同步肥惭。Swagger 讓部署管理和使用功能強(qiáng)大的API從未如此簡單盯仪。

官網(wǎng)：http://swagger.io/

GitHub地址：https://github.com/swagger-api/swagger-ui

二、為什么要使用Swagger2蜜葱？

Swagger2引入的好處全景，同樣也是手寫Api文檔的幾個痛點(diǎn)：

文檔需要更新的時(shí)候，需要再次發(fā)送一份給前端牵囤，也就是文檔更新交流不及時(shí)爸黄。
接口返回結(jié)果不明確
不能直接在線測試接口，通常需要使用工具奔浅，比如postman
接口文檔太多，不好管理

三诗良、使用Swagger2

3.1汹桦、添加Swagger2依賴：

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

3.2、創(chuàng)建Swagger2配置類

使用@Configuration來表示該類是個配置類
使用@EnableSwagger2來啟用Swagger2

@Configuration
@EnableSwagger2//啟用Swagger2
public class Swagger2Config {

    //從配置文件中獲取屬性值
    @Value("${swagger2.basepackage}")
    private String basepackage;


    /**
     * buildDocket()用于創(chuàng)建Docket的Bean鉴裹，
     * buildApiInfo()創(chuàng)建Api的基本信息舞骆，用于顯示在文檔頁面上钥弯。
     * select()函數(shù)返回一個ApiSelectorBuilder實(shí)例，用來控制哪些接口暴露給Swagger2來展現(xiàn)督禽。
     *      一般采用指定掃描的包路徑來定義脆霎，本例中Swagger會掃描controller包下所有定義的API，并產(chǎn)生文檔內(nèi)容（除了被@ApiIgnore指定的請求）狈惫。
     *
     * @return
     */
    @Bean
    public Docket buildDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basepackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo buildApiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構(gòu)建RESTful API文檔")
                .description("構(gòu)建簡單優(yōu)雅的Restfun風(fēng)格的api")
                .termsOfServiceUrl("https://github.com/caychen")
                .contact(new Contact("Cay", "", "412425870@qq.com"))
                .version("1.0")
                .build();
    }
}

3.3睛蛛、添加文檔內(nèi)容

@Api：用于controller請求類上，說明該類的說明

@Api(value = "用戶Controller")
public class UserController {}

@ApiOperation：用在controller類的具體請求方法上胧谈，說明方法的作用和用途

value：說明方法的用途忆肾、作用

notes：備注說明

@ApiOperation(value = "獲取User列表", notes = "獲取所有User對象")
public List<User> getUserList() {}

@ApiModel：用于響應(yīng)類上，表示一個返回響應(yīng)數(shù)據(jù)的信息(這種一般用在post創(chuàng)建的時(shí)候菱肖，使用@RequestBody這樣的場景客冈，請求參數(shù)無法使用@ApiImplicitParam注解進(jìn)行描述的時(shí)候）

@ApiModelProperty：用在相應(yīng)類的屬性上，描述響應(yīng)類的屬性

value：參數(shù)名稱

required：是否必須boolean

hidden：是否隱藏hidden

@ApiModel(value = "用戶對象User")
public class User implements Serializable {
    @ApiModelProperty(value = "用戶id", name = "uid")
    private Integer uid;
    @ApiModelProperty(value = "用戶名", name = "uname")
    private String uname;
    @ApiModelProperty(value = "用戶年齡", name = "uage")
    private Integer uage;
}

@ApiResponses：用于controller類的具體請求方法上稳强，來表示一組響應(yīng)

@ApiResponse：用在@ApiResponses中场仲，一般用于表達(dá)一個錯誤的響應(yīng)信息

code：狀態(tài)碼
message：信息
response：響應(yīng)的類型，默認(rèn)void

@ApiImplicitParams：用在請求的方法上退疫，表示一組參數(shù)說明

@ApiImplicitParam：用在@ApiImplicitParams注解中渠缕，指定一個請求參數(shù)的各個方面

name：對應(yīng)方法中接收參數(shù)名，必須指定

value：參數(shù)的說明蹄咖、解釋

required：參數(shù)是否必須傳參褐健，必須指定

dataType：參數(shù)類型，默認(rèn)String澜汤，如果類型名稱相同蚜迅，請指定全路徑，例如 dataType = “java.util.Date”俊抵，springfox會自動根據(jù)類型生成模型

defaultValue：參數(shù)的默認(rèn)值

paramType：參數(shù)放在哪個地方谁不，必須指定

header --> 請求參數(shù)從header請求頭中獲取，需要使用@RequestHeader

query --> 請求參數(shù)從url的請求中獲取徽诲，@RequestParam刹帕。例如 ?query=q ,jquery ajax中data設(shè)置的值也可以，例如 data:{query:”q”}谎替，在Controller中不需要添加注解就可以直接接收偷溺。

path（用于restful接口）--> 請求參數(shù)從path中獲取：需要使用@PathVariable

body --> 需要使用@RequestBody接收數(shù)據(jù)钱贯，POST有效

form --> 表單提交挫掏，必須使用post提交

@PutMapping("/{id}")
@ApiOperation(value = "更新指定user對象", notes = "根據(jù)url的id來指定更新對象，并根據(jù)傳過來的user信息來更新用戶詳細(xì)信息")
@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "需要更新的用戶id", required = true, dataType = "Integer", paramType = "path"),
    @ApiImplicitParam(name = "user", value = "用戶詳細(xì)實(shí)體user", required = true, dataType = "User", paramType = "body")
})
public String updateUser(@PathVariable Integer id, @RequestBody User user) {}

@ApiIgnore：使用該注解忽略Controller的api方法

具體參照UserController：

@RestController
@RequestMapping("/user")
@Api(value = "用戶Controller")
public class UserController {

    private static final Logger logger = LoggerFactory.getLogger(UserController.class);

    @Autowired
    private IUserService userService;

    //@RequestMapping("/")
    @GetMapping("/")
    @ApiOperation(value = "獲取User列表", notes = "獲取所有User對象")
    public List<User> getUserList() {
        logger.info("獲取User列表...");
        return userService.getUserList();
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "獲取用戶詳情", notes = "根據(jù)url中用戶id來獲取該用戶的詳情")
    @ApiImplicitParam(name = "id", value = "用戶id", required = true, dataType = "Integer", paramType = "path")
    public User getById(@PathVariable Integer id) {
        logger.info("獲取id為{}的User...", id);
        return userService.getById(id);
    }

    @PostMapping("/")
    @ApiOperation(value = "新增User", notes = "根據(jù)User對象創(chuàng)建用戶")
    @ApiImplicitParam(name = "user", value = "用戶詳細(xì)實(shí)體user", required = true, dataType = "User", paramType = "body")
    public String addUser(@RequestBody User user) {
        logger.info("新增User對象...");
        int result = userService.addUser(user);
        if (result == 1) {
            return "success";
        } else {
            return "error";
        }
    }

    @PutMapping("/{id}")
    @ApiOperation(value = "更新指定user對象", notes = "根據(jù)url的id來指定更新對象秩命，并根據(jù)傳過來的user信息來更新用戶詳細(xì)信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "需要更新的用戶id", required = true, dataType = "Integer", paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用戶詳細(xì)實(shí)體user", required = true, dataType = "User", paramType = "body")
    })
    public String updateUser(@PathVariable Integer id, @RequestBody User user) {
        logger.info("更新id為{}的User對象...", id);
        user.setUid(id);
        int result = userService.updateUser(id, user);
        if (result == 1) {
            return "success";
        } else {
            return "error";
        }
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "刪除指定user對象", notes = "根據(jù)url中的id來刪除user對象")
    @ApiImplicitParam(name = "id", value = "需要刪除user對象的id", required = true, dataType = "Integer", paramType = "path")
    public String deleteUser(@PathVariable Integer id) {
        logger.info("刪除id為{}的User對象...", id);
        int result = userService.deleteUser(id);
        if (result == 1) {
            return "success";
        } else {
            return "error";
        }
    }
}

3.4尉共、啟動項(xiàng)目褒傅，訪問http://ip:port/swagger-ui.html

Swagger文檔頁面.png

依次點(diǎn)開每個url，即可在線調(diào)試袄友。

二十三熬粗、Spring Boot使用Swagger2生成API文檔

二十三搀玖、Spring Boot使用Swagger2生成API文檔