• Spring Boot 之 Swagger

    文章目录

    Swagger

    Swagger介绍

    • Swagger 是一套基于 OpenAPI 规范构建的开源工具
      • OpenAPI Specification，OAS
      • 帮助设计、构建、记录以及使用 REST API
    • OpenAPI 规范是在2015年由OpenAPI Initiative 捐赠给 Linux 基金会
      • 该规范创建了 RESTful 接口规范
      • 通过有效映射与之关联的所有资源和操作来轻松开发和使用 API
    • 主要部分
      • Swagger Editor
        • 基于浏览器的编辑器
        • 可以编写 OpenAPI 规范
      • Swagger UI
        • 会将编写的 OpenAPI 规范呈现为交互式的 API 文档
        • 使用浏览器来查看并且操作 Rest API
      • Swagger Codegen
        • 通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程
    • SpringBoot 项目整合 swagger 需要用到两个依赖（旧版）
      • 用于自动生成 swagger 文档
        • springfox-swagger2
          • 用于帮助自动生成描述 API 的 json 文件
        • ``springfox-swagger-ui`
          • 将描述 API 的 json 文件解析出来
          • 用一种更友好的方式呈现出来
      • 新版只需要 SpringBoot 起步依赖
        • springfox-boot-starter
    版本

    新版本和老版本的区别主要体现在以下 4 个方面

    1. 依赖项的添加不同：新版本只需要添加一项
      • 老版本需要添加两项
    2. 启动 Swagger 的注解不同：新版本使用的是 @EnableOpenApi
      • 老版本是 @EnableSwagger2
    3. Docket：文档摘要信息的文件类型配置不同：新版本配置的是 OAS_3
      • 老版本是 SWAGGER_2
    4. Swagger UI 访问地址不同：新版本：http://localhost:8080/swagger-ui/
      • 老版本访问地址是：http://localhost:8080/swagger-ui.html

    使用

    依赖
    
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>3.0.0version>
dependency>

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


<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-boot-starterartifactId>
    <version>3.0.0version>
dependency>

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    常用注解说明
    • 只要 controller 方法返回实体类对象，在 Swagger 文档中就会有实体类数据模型
      • 配置 @ApiModel、@ApiModelProperty 注解以描述实体类属性、方法
    /*
用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，所以不需要配置"
*/
@Api(tags="APP用户注册Controller")
-----------------------------------------------------------
/*
用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
*/
@ApiOperation(value="用户注册",notes="必须是数字")
-----------------------------------------------------------
/*
* @ApiImplicitParams：用在请求的方法上，表示一组参数说明
* 	参数是 pojo 类型，不能使用 @ApiImplicitParams 注解
* @ApiImplicitParam：在 @ApiImplicitParams 注解内部，指定一个请求参数的各个方面
* 	name：参数名
* 	value：参数的汉字说明、解释
*   required：参数是否必须存在
*   paramType：参数位置
*   	· header：获取参数 @RequestHeader
*      	· query： 获取参数 @RequestParam
*     	· path：用于 restful 接口，获取参数 @PathVariable
*     	· body、form（不常用）    
* 	dataType：参数类型，默认 String；dataType="Integer"       
* 	defaultValue：参数的默认值
*/
@ApiImplicitParams({
    @ApiImplicitParam(name="mobile", value="手机号", required=true, paramType="form"),
    @ApiImplicitParam(name="password", value="密码", required=true, paramType="form"),
    @ApiImplicitParam(name="age", value="年龄", required=true, paramType="form",dataType="Integer")
})
-----------------------------------------------------------
/*
* @ApiResponses：用在请求的方法上，表示一组响应
* @ApiResponse：在 @ApiResponses 内部，一般用于表达一个错误的响应信息
* 	code：状态码，例如：400
* 	message：返回信息，例如"请求参数没填好"
* 	response：抛出异常的类
*/
@ApiOperation(value = "select1请求",notes = "多参，多类型")
@ApiResponses({
    @ApiResponse(code=400,message="请求参数没填好"),
    @ApiResponse(code=404,message="路径没有或路径不对")
})
-----------------------------------------------------------
/*
* @ApiModel：描述实体类，一般用在 post 创建时，使用 @RequestBody 的场景，
* 请求参数无法使用 @ApiImplicitParam 注解进行描述的场景使用
* @ApiModelProperty：描述实体类属性
*/
@ApiModel(value = "Demo类",description = "测试")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Demo {
    @ApiModelProperty("用户id")
    private Integer id;

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    • 33
    • 34
    • 35
    • 36
    • 37
    • 38
    • 39
    • 40
    • 41
    • 42
    • 43
    • 44
    • 45
    • 46
    • 47
    • 48
    • 49
    • 50
    • 51
    • 52
    • 53
    • 54
    • 55
    • 56
    • 57
    • 58
    • 59
    • 60
    配置类

    • select().apis() 扫描接口方式

      • basePackage: 指定要扫描的包
      • any: 扫描全部
      • none：都不扫描
        • withClassAnnotation: 扫描类上注解,传入注解反射对象
      • withMethodAnnotation: 扫描方法上的注解

    • .paths()：过滤的请求路径

      • any()：任何请求都扫描
      • none()：任何请求都不扫描
      • regex(final String pathRegex)：正则表达式控制
      • ant()：指定要扫描的路径
    @EnableOpenApi  //Swagger 3 使用此注解
@Configuration
public class Swagger2Config {

    // 配置 docket 以配置 Swagger 具体参数
    @Bean
    public Docket docket(Environment environment){
        // 获取当前环境是否是生产环境：pro
        boolean flag = environment.acceptsProfiles(Profiles.of("pro"));                
        return new Docket(DocumentationType.OAS_30) // 文档类型：3.0 版本 OAS_30
            // 是否开启 Swagger: 开发环境开启，生产环境关闭
            .enable(!flag)
            // api 的元信息设置
            .apiInfo(apiInfo())
            // 配置分组：多个分组需要配置多个docket
            .groupName("测试1")
            // 接口调试地址
            .host()
            // 配置扫描接口
            .select()
            // 扫描方式：RequestHandlerSelectors配置
            .apis(RequestHandlerSelectors. basePackage("security.controller"))
            // 过滤路径
            .paths(PathSelectors.ant("/user/**"))
            // 构建者模式
            .build()
            // 支持的通讯协议集合
            .protocols(newHashSet("https", "http"))
            // 授权信息设置，必要的header token等认证信息
            .securitySchemes(securitySchemes())
            // 授权信息全局应用
            .securityContexts(securityContexts());;
    }

    // 配置 Swagger 基本信息：apiInfo
    private ApiInfo apiInfo(){
        // 只能使用构造方法创建或使用默认信息：所以一项都不能少
        return new ApiInfo(
            "Swagger 测试使用",													 // 标题
            "初次学习 Swagger", 												 // 描述
            "v1.0", 															// 版本
            "urn:tos",															// 组织：termsOfServiceUrl
            new Contact("demo", "http:localhost:8080/", "2417500668@qq.com"),	// 作者信息
            "Apache 2.0", 														// 许可证
            "http://www.apache.org/licenses/LICENSE-2.0", 						// 许可证链接
            new ArrayList<>());													// 拓展
    }

    /**
     * 设置授权信息
     */
    private List<SecurityScheme> securitySchemes() {
        ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
        return Collections.singletonList(apiKey);
    }

    /**
     * 授权信息全局应用
     */
    private List<SecurityContext> securityContexts() {
        return Collections.singletonList(
            SecurityContext.builder()
            .securityReferences(Collections.singletonList(
                new SecurityReference("BASE_TOKEN", 
                                      new AuthorizationScope[]{
                                          new AuthorizationScope("global", "")}))
                               ).build());}

    @SafeVarargs
    private final <T> Set<T> newHashSet(T... ts) {
        if (ts.length > 0) {
            return new LinkedHashSet<>(Arrays.asList(ts));
        }
        return null;
    }

    /**
     * 通用拦截器排除swagger设置，所有拦截器都会自动加 swagger 相关的资源排除信息
     */
    @SuppressWarnings("unchecked")
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        try {
            Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
            List<InterceptorRegistration> registrations = 
                (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
            if (registrations != null) {
                for (InterceptorRegistration interceptorRegistration : registrations) {
                    interceptorRegistration
                        .excludePathPatterns("/swagger**/**")
                        .excludePathPatterns("/webjars/**")
                        .excludePathPatterns("/v3/**")
                        .excludePathPatterns("/doc.html");
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    • 33
    • 34
    • 35
    • 36
    • 37
    • 38
    • 39
    • 40
    • 41
    • 42
    • 43
    • 44
    • 45
    • 46
    • 47
    • 48
    • 49
    • 50
    • 51
    • 52
    • 53
    • 54
    • 55
    • 56
    • 57
    • 58
    • 59
    • 60
    • 61
    • 62
    • 63
    • 64
    • 65
    • 66
    • 67
    • 68
    • 69
    • 70
    • 71
    • 72
    • 73
    • 74
    • 75
    • 76
    • 77
    • 78
    • 79
    • 80
    • 81
    • 82
    • 83
    • 84
    • 85
    • 86
    • 87
    • 88
    • 89
    • 90
    • 91
    • 92
    • 93
    • 94
    • 95
    • 96
    • 97
    • 98
    • 99
    • 100

    皮肤定制

    导入不同的包实现不同的皮肤定义

    1. 默认访问： http://localhost:8080/swagger-ui.html

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

      • 1
      • 2
      • 3
      • 4
      • 5

    2. bootstrap-ui： http://localhost:8080/doc.html

      
<dependency>
   <groupId>com.github.xiaoymingroupId>
   <artifactId>swagger-bootstrap-uiartifactId>
   <version>1.9.1version>
dependency>

      • 1
      • 2
      • 3
      • 4
      • 5
      • 6

    3. Layui-ui：http://localhost:8080/docs.html

      
<dependency>
   <groupId>com.github.caspar-chengroupId>
   <artifactId>swagger-ui-layerartifactId>
   <version>1.1.3version>
dependency>

      • 1
      • 2
      • 3
      • 4
      • 5
      • 6

    4. mg-ui：http://localhost:8080/document.html

      
<dependency>
   <groupId>com.zyplayergroupId>
   <artifactId>swagger-mg-uiartifactId>
   <version>1.0.6version>
dependency>

      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
  • 相关阅读:
    分组背包问题
    中级JAVA程序员应该掌握的数据结构知识
    (02)Cartographer源码无死角解析-(09) gflags与glog简介、及其main函数讲解
    JavaScript:实现 jugglerSequence杂耍者序列算法 （附完整源码）
    JavaScript之运算符相关知识
    day01-从一个基础的socket服务说起
    nmap参数详解
    配置错误的smb共享
    信息安全技术实验：数据的加密与解密
    125. 验证回文串
  • 原文地址：https://blog.csdn.net/qq_66991094/article/details/127660820