SpringBoot2.x 整合 Swagger2

【简介】

Swagger是一个RESTFUL 接口的文档在线自动生成和功能测试的框架。

Swagger 是一个规范和完整的框架。用于生成、描述、调用和可视化RestFul风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法、参数和模型紧密集成到服务器的代码，允许Api 来始终保持同步，Swagger让部署管理和使用功能强大的Api。

---

【官网】

http://swagger.io/

GIthub地址：

https://github.com/swagger-api/swagger-ui

---

【推荐文章】

Spring Boot 2.x基础教程：使用Swagger2构建强大的API文档

http://blog.didispace.com/spring-boot-learning-21-2-2/

Spring Boot中使用Swagger2构建强大的RESTful API文档
http://blog.didispace.com/springbootswagger2/

---

【本文项目地址】

https://github.com/qidasheng2012/springboot2.x_swagger2

---

【Maven 依赖】

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.9.2version>
dependency>

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.9.2version>
dependency>

---

【配置类】

package com.it.swagger2.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 // 启用swagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.it.swagger2")) //扫描路径
                .paths(PathSelectors.any()) //定义哪些路径的接口需要生成文档
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger2 接口文档") //文档首页标题
                .description("接口文档") //文档描述信息
                .contact(new Contact("name", "url", "email")) //创建者信息
                .version("1.0") //文档版本
                .build();
    }
}

通过@Configuration注解，让SpringBoot来加载该类的配置

通过@EnableSwagger2注解来启用Swagger2Config。

通过ApiInfoBuilder() 用来创建该Api的基本信息（这些信息会展示在文档页面当中）。

select()函数返回一个ApiSelectBuilder实例来控制哪些接口来暴露给swagger2来展示，一般采用指定扫描的包路径来定义。

Swagger会扫描该包下的所有Controller定义的Api，并产生文档内容。(除了被@ApiIgnore指定的请求)。

---

【常用注解】

【@Api】用在请求的类上，表示对类的说明

tags：说明该类的作用，可以在UI界面上看到的注解
value：该controller简短的标题
description：详细介绍
producer：说明该controller是使用什么显示层格式的
protocols：使用什么协议

---

【@ApiOperation】用在请求的方法上，说明方法的用途、作用

value：该方法简短的变态
note：详细介绍
code：正常情况下返回的状态码是多少
httpMethod：使用什么http方法
response：响应什么对象，这里写的是响应的对象的字节码

---

【@ApiImplicitParams】用在请求的方法上，表示一组参数说明

【@ApiImplicitParam】用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
dataType：参数类型，默认String，其它值dataType="Integer"       
defaultValue：参数的默认值
paramType：参数放在哪个地方
    · header --> 请求参数的获取：@RequestHeader
    · query --> 请求参数的获取：@RequestParam
    · path（用于restful接口）--> 请求参数的获取：@PathVariable
    · body（不常用）
    · form（不常用）    

【例】

package com.it.swagger2.controller;

import com.it.swagger2.domain.User;
import io.swagger.annotations.*;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@Slf4j
@RestController
@RequestMapping("/user")
@Api(tags = "用户 Controller")
public class UserController {

    // 创建用户
    @ApiIgnore // 忽略，不生成文档
    @PostMapping
    public User create(@RequestBody User user) {
        return user;
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "根据ID获取用户信息", notes = "根据ID获取用户信息详细描述")
    public User getUser(@PathVariable("id") Long id) {
        return new User(1L, "张三", 23);
    }

    @ApiOperation(value = "删除用户", notes = "删除用户详细描述")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户的唯一标识", required = true),
            @ApiImplicitParam(name = "name", value = "用户名", required = false)
    })
    @ApiResponses({
            @ApiResponse(code = 401, message = "禁止访问")
    })
    @DeleteMapping("/{id}/{name}")
    public String deleteUsers(@PathVariable("id") Long id, @PathVariable("name") String name) {
        return "删除成功";
    }

}

---

【@ApiResponses】用在请求的方法上，表示一组响应

【@ApiResponse】 用在@ApiResponses中，一般用于表达一个错误的响应信息

code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

---

【@ApiModel】用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）

【@ApiModelProperty】用在属性上，描述响应类的属性

【例】

package com.it.swagger2.domain;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户实体类")
public class User {

    @ApiModelProperty(value = "主键ID", example = "1L")
    private Long id;
    @ApiModelProperty(value = "姓名", example = "张三")
    private String name;
    @ApiModelProperty(value = "年龄", example = "23")
    private Integer age;

}

---

【@ApiIgnore】使用该注解忽略这个API

【@ApiError】发生错误返回的信息

---

【文档查看地址】

http://localhost:8080/swagger-ui.html

报文地址：

http://localhost:8080/v2/api-docs

---

【优缺点】

优点： 简单 , 实时 , 可测试 , 容易管理

缺点： 代码侵入性太强

---

【推荐文章】

Swagger接口分类与各元素排序问题详解
Swagger静态文档的生成