spring boot 下swagger2 的使用

acc8226

发布于 2022-05-17 19:44:16

6280

发布于 2022-05-17 19:44:16

文章被收录于专栏：叽叽西

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

swagger 官方Demo供参考 https://petstore.swagger.io/

swagger注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

API详细说明

@Api(tags = "收付费方式变更") 常用

@ApiOperation("获取用户列表") 常用

@ApiParam(value = "用户Id") 常用

@ApiImplicitParam：作用在方法上，表示单独的请求参数, 一个非常强大且重要的注解, 作用和ApiParam类似

开始使用

pom中导入dependency

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

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

Application 中启用 @EnableSwagger2
config的配置类

package com.abc.xxx;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author zh
 * @ClassName cn.saytime.Swgger2
 * @Description
 * @date 2017-07-10 22:12:31
 */
@Configuration
public class Swagger2 {

    private static final String SWAGGER_SCAN_BASE_PACKAGE = "com.baomidou.ant.abc";
    private static final String VERSION = "0.0.1";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() // 选择那些路径和api会生成document
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any())// 对根下所有路径进行监控
                .build();
    }

    private static ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .version(VERSION)
                .build();
    }
}

/**
 * <p>
 * 收付费方式变更总表
 前端控制器
 * </p>
 *
 * @author someone
 * @since 2019-07-15
 */
@Api(tags = "收付费方式变更")
@RestController
@RequestMapping("/test")
public class PaychangeTotalController {

    /**
     * 查询用户列表
     *
     * @return
     */
    @ApiOperation("获取用户列表")
    @GetMapping("/users/{id}")
    public String getUserList(@ApiParam(value = "用户", required = true) @PathVariable String id) {
        return "Npp";
    }

    @ApiOperation("小猫变小狗")
    @PostMapping( value = "/edit")
    public Result<?> edit (@RequestBody Cat cat){
        Dog dog = new Dog();
        dog.setNickName("小白");
        return JSONResult.ok(dog);
    }
}

总结常用swagger-ui注解

@Api() 用于类 该注解将一个Controller（Class）标注为一个swagger资源（API）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。该注解包含以下几个重要属性：

tags：API分组标签。具有相同标签的API将会被归并在一组内展示。
value：如果tags没有定义，value将作为Api的tags使用
description：对该API的详细描述信息
position：如果一个controller中有多个请求方法，可以通过该属性来指定API在swagger-ui中的显示顺序

@ApiOperation() 用于方法 在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有：

value：对操作的简单说明，长度为120个字母，60个汉字。
notes：对操作的详细说明。
httpMethod：HTTP请求的动作名，可选值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。 code：默认为200，有效值必须符合标准的HTTP Status Code Definitions。

@ApiParam() 用于方法，参数，字段说明 增加对参数的元信息说明，主要的属性有：

required：指定该参数是否为必传参数 value：对该参数含义的简短说明

@ApiResponses（）用于包装类 注解@ApiResponse的包装类，数组结构。

即使需要使用一个@ApiResponse注解，也需要将@ApiResponse注解包含在注解@ApiResponses内。

@ApiResponse（）用于方法的返回结果 描述一个操作可能的返回结果。

当REST API请求发生时，这个注解可用于描述所有可能的成功与错误码。可以用，也可以不用这个注解去描述操作的返回类型，但成功操作的返回类型必须在@ApiOperation中定义。如果API具有不同的返回类型，那么需要分别定义返回值，并将返回类型进行关联。但Swagger不支持同一返回码，多种返回类型的注解。注意：这个注解必须被包含在@ApiResponses注解中。

字段说明： code：HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。 message：用于对返回信息作详细说明，对请求结果的描述信息 response：返回类型信息，必须使用完全限定类名，比如“com.xyz.cc.Person.class”。 responseContainer：如果返回类型为容器类型，可以设置相应的值。有效值为 "List", "Set" or "Map"，其他任何无效的值都会被忽略

2）Model的注解 @ApiModel() 用于类 提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内，所有的类将自动被内省（introspected），但利用这个注解可以做一些更加详细的model结构说明。主要属性有： value：model的别名，默认为类名 description：对model的详细描述

** @ApiModelProperty() 用于model类的属性** 表示对model属性的说明或者数据操作更改，主要的属性有：

value：描述 required：标识该属性是否为必须值 example：给出该属性的示例值 allowableValues : 可选值, 像这样@ApiModelProperty(allowableValues = "range[1,5]") 或者 @ApiModelProperty(allowableValues = "111, 222")

3）其他注解 @ApiIgnore() 用于类，方法，方法参数

表示这个方法或者类被忽略

@ApiImplicitParam() 用于方法

表示单独的请求参数

@ApiImplicitParams() 用于方法

该注解可以包含多个 @ApiImplicitParam

swagger2 如何匹配多个controller

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.shubing"))
            .paths(PathSelectors.any())
            .build();
}

或者

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            .paths(PathSelectors.any())
            .build();
}

使用以下两种，都是错误的

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.shubing.*.controller"))
            .paths(PathSelectors.any())
            .build();
}
@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.shubing.course.controller"))
            .apis(RequestHandlerSelectors.basePackage("com.shubing.user.controller"))
            .paths(PathSelectors.any())
            .build();
}

不同环境中配置是否启用swagger

@Value("${swagger.enable}")
private boolean enableSwagger;

@Bean 
public Docket customImplementation(){
    return new Docket(SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(enableSwagger) //<--- Flag to enable or disable possibly loaded using a property file
        .includePatterns(".*pet.*");
}

然后，需要在dev和test环境中配置：