SpringBoot-11-Swagger

OpenAPI规范(OpenAPI Specification简称OAS)是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。Swagger是目前最瘦欢迎的OpenAPI规范API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。

Swagger可以随项目生成强大的RESTful API文档，减少开发人员的工作量(不用自己写API接口文档了)。使用Swagger，只需要在代码中添加一些注解即可生成API接口文档，便于同步更新API文档的说明。另外生成API文档页面带有测试功能，可以用来调试每个RESTful API接口。

2020.07出了Swagger3.0，但是目前文档和网上教程都不太完善，后续学有余力再研究一下3.0，具体的资料都在官方github。

Swagger 2.x基本使用

3.0已经有starter了，导一个就可以，但是2.9.2还需要导两个依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

然后需要一个配置类，用来配置一些基本信息，格式基本是固定的：

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//扫描带有ApiOperation注解的方法
                .paths(PathSelectors.any())
                .build();
    }

    // 创建api的基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用户账号接口文档")
                .description("集成Swagger2构建Restful APIS")
                .termsOfServiceUrl("http://www.xxxxx.com/")
                .contact(new Contact("youkee", "", "xdutao@foxmail.com"))
                .license("采用 Apache 2.0开源许可证")
                .version("1.0.0")
                .build();
    }
}

这么看可能有点一头雾水，但是现在只配置这一点东西，然后打开http://localhost:8080/swagger-ui.html，看一下页面上的内容，就大概知道了：

等于说这个配置类在配接口文档页面的基本信息和一些扫描规则。

下面写一个简单的pojo User和UserController

@Data
public class User {
    private Integer id;
    private String name;
}

@Controller
public class UserController {

    private Integer count = 1000;

    @GetMapping("/users")
    public ModelAndView getUserCount() {
        ModelAndView modelAndView = new ModelAndView();
        modelAndView.addObject("userCount", count);
        modelAndView.setViewName("userCount");
        return modelAndView;
    }


    @GetMapping("/users/{id}")
    public @ResponseBody User getUserById(@PathVariable("id") Integer id) {
        User user = new User();
        user.setId(id);
        user.setName("bob" + id);
        return user;
    }

    @PostMapping("/users/{id}/{name}")
    public ModelAndView insertUser(@PathVariable("id") Integer id,
                                   @PathVariable("name") String name) {
        ModelAndView modelAndView = new ModelAndView();
        User user = new User();
        user.setId(id);
        user.setName(name);
        modelAndView.addObject("user", user);
        count++;
        modelAndView.addObject("userCount", count);
        modelAndView.setViewName("insertSuccess");
        return modelAndView;
    }
}

但是在没有任何注解的情况下，Swagger是没办法帮你生成这些方法的接口文档的，下面先列举一些注释的用途，然后再结合代码看一下具体的作用。列举的注解和属性都不是特别全的，可以点进源码看一下，代码的注释都说的非常清楚；或者看官网文档，不过官方文档也已经更新成3.0的用法了，后续再好好学一下。

• @Api：用在类上，说明该类的作用

• @ApiOperation：用在方法上，说明方法的作用

• @ApiImplicitParams：用在方法上包含一组参数说明

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

  • paramType：参数放在哪个地方

    • header --> 请求参数的获取@RequestHeader
    • query --> 请求参数的获取@RequstParam
    • path --> 请求参数的获取@PathVariable
    • body --> 请求参数的获取@RequestBody
    • form --> form-data获取参数

  • name：参数名

  • dataType：参数类型

  • required：参数是否必须传

  • value：参数的意思

  • defaultValue：参数的默认值

• @ApiResponses：用于表示一组响应

• @ApiResponse：用在@ApiResponses注解中，用于表达一个错误的响应信息

  • code：数字，比如400,404
  • message：信息，例如“请求参数不合法”
  • response：抛出异常的类

• @ApiIgnore：使用该注解忽略这个API，不在页面上显示

• @ApiModel：描述一个Model的信息

• @ApiModel：描述一个Model的属性

先对User改造一下：

@Data
@ApiModel(value = "User", description = "用户对象")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1001")
    private Integer id;
    @ApiModelProperty(value = "用户姓名", example = "张三")
    private String name;
}

然后controller的代码是改动最多的，需要加很多注解：

@Controller
@Api(tags = "用户控制层，负责处理用户相关请求")
public class UserController {

    private Integer count = 1000;

    @ApiOperation(value = "获取用户总人数", notes = "查询数据库中所有用户")
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 401, message = "请求路径没有相应权限"),
            @ApiResponse(code = 403, message = "请求路径呗隐藏，不能访问"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
            @ApiResponse(code = 405, message = "请求方法不支持")
    })
    @GetMapping("/users")
    public ModelAndView getUserCount() {
        ModelAndView modelAndView = new ModelAndView();
        modelAndView.addObject("userCount", count);
        modelAndView.setViewName("userCount");
        return modelAndView;
    }


    @ApiOperation(value = "查询用户", notes = "根据路径中的id在数据库中查询用户")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "path", name = "id", value = "用户ID", dataType = "Integer")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "缺少必要的请求参数"),
            @ApiResponse(code = 401, message = "请求路径没有相应权限"),
            @ApiResponse(code = 403, message = "请求路径被隐藏，不能访问"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
            @ApiResponse(code = 405, message = "请求方法不支持")
    })
    @GetMapping("/users/{id}")
    public @ResponseBody User getUserById(@PathVariable("id") Integer id) {
        User user = new User();
        user.setId(id);
        user.setName("bob" + id);
        return user;
    }


    @ApiOperation(value = "插入用户", notes = "根据路径中的id，name创建用户并插入数据库")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "path", name = "id", value = "用户ID", dataType = "Integer"),
            @ApiImplicitParam(paramType = "path", name = "name", value = "用户姓名", dataType = "String")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "缺少必要的请求参数"),
            @ApiResponse(code = 401, message = "请求路径没有相应权限"),
            @ApiResponse(code = 403, message = "请求路径被隐藏，不能访问"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
            @ApiResponse(code = 405, message = "请求方法不支持")
    })
    @PostMapping("/users/{id}/{name}")
    public ModelAndView insertUser(@PathVariable("id") Integer id,
                                   @PathVariable("name") String name) {
        ModelAndView modelAndView = new ModelAndView();
        User user = new User();
        user.setId(id);
        user.setName(name);
        modelAndView.addObject("user", user);
        count++;
        modelAndView.addObject("userCount", count);
        modelAndView.setViewName("insertSuccess");
        return modelAndView;
    }
}

看着比较多，但是对应着生成的接口文档看一下，就比较清晰了：

剩下的ModelAndView是因为返回方法中返回的有，所以也当Model处理了，没有@ApiModel注解，所以内容也比较乱。