小言_互联网的博客

Spring Boot 之 Swagger

2022-11-06 20:05 267人阅读  评论(0)

文章目录

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

使用

依赖

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

<!-- springboot启动依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

常用注解说明

  • 只要 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;

配置类

  • 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. 默认访问： http://localhost:8080/swagger-ui.html

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

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

    <!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

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

    <!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

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

    <!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

转载：https://blog.csdn.net/qq_66991094/article/details/127660820
查看评论
* 以上用户言论只代表其个人观点，不代表本网站的观点或立场