Spring Boot2 入门学习14.使用SpringDoc的 Swagger

Posted 2021-06-27 编程圈子

Spring Boot2 入门学习14.使用SwaggerUI3

• 一、说明
• • 1. Swagger2、3版本区别
  • 2. 关于SpringFox
  • 3. 关于SpringDoc
• 二、使用SpringDoc
• • 1. 引用包
  • 2. 一些swagger3注解
  • 3. 修改分组
  • 4. 访问
• 三、使用knife4j

一、说明

1. Swagger2、3版本区别

Swagger3 和 Swagger2 使用有一些区别。 Swagger2 基于OpenApi3在2017年停止维护， 使用Swagger3（也是基于OpenApi3）代替。

• Swagger2包名： io.swagger
• Swagger3包名： io.swagger.core.v3
• Swagger3 支持Spring5、OpenApi 3.0.3

2. 关于SpringFox

SpringFox开源项目用来将Swagger2集成到Spring中。

3. 关于SpringDoc

• SpringDoc开源项目用来将Swagger3集成到Spring中。
• 该组织的项目支持Swagger 页面Oauth2登陆。

二、使用SpringDoc

1. 引用包

不要使用SpringFox或Swagger的依赖，直接使用springdoc-openapi-ui：

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.3.1</version>
   </dependency>

2. 一些swagger3注解

swagger2	OpenAPI 3	注解位置
@Api	@Tag(name = “接口类描述”)	Controller 类
@ApiOperation	@Operation(summary =“接口方法描述”)	Controller 方法
@ApiImplicitParams	@Parameters	Controller 方法
@ApiImplicitParam	@Parameter(description=“参数描述”)	Controller 方法的 @Parameters 里
@ApiParam	@Parameter(description=“参数描述”)	Controller 方法的参数上
@ApiIgnore	@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden	-
@ApiModel	@Schema	DTO类上
@ApiModelProperty	@Schema	DTO属性上

3. 修改分组

   @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .setGroup("springshop-public")
                .pathsToMatch("/public/**")
                .build();
    }
  
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .setGroup("springshop-admin")
                .pathsToMatch("/admin/**")
                .build();
    }

如果只有一个Docket，可以使用配置文件来配置：

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**

4. 访问

http://localhost/swagger-ui

三、使用knife4j

依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-springdoc-ui</artifactId>
    <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
    <version>3.0.2</version>
</dependency>