参考链接：
SpringBoot3.x使用Swagger - 掘金](https://juejin.cn/post/7299800370489966630#heading-22)

导入依赖：

1
2
3
4
5
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

配置：

  • 开发环境
  • 开发环境通常会开启Swagger文档，方便前端查阅文档
1
2
3
4
5
6
7
8
springdoc:
  api-docs:
    enabled: true # 开启OpenApi接口
    path: /user-service/v3/api-docs  # 自定义文档接口路径，默认为 "/v3/api-docs"
  swagger-ui:
    enabled: true # 开启swagger界面，依赖OpenApi，需要OpenApi同时开启
    path: /user-service/swagger-ui/index.html # 自定义UI路径，默认为"/swagger-ui/index.html"

  • 生产环境
  • 切记生产环境要关闭文档
1
2
3
4
5
springdoc:
  api-docs:
    enabled: false # 关闭OpenApi接口
  swagger-ui:
    enabled: false # 关闭swagger界面

向spring容器中注入swagger配置类：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI swaggerOpenApi() {
        return new OpenAPI()
                .info(new Info().title("XXX平台YYY微服务")
                        .description("描述平台多牛逼")
                        .version("v1.0.0"))
                .externalDocs(new ExternalDocumentation()
                        .description("设计文档")
                        .url("https://juejin.cn/user/254742430749736/posts"));
    }
}

上面配置后暂时的界面为：
image.png

常用注解：

注解 标注位置 作用
@Tag controller 类 标识 controller 作用
@Parameter 参数 标识参数作用
@Parameters 参数 参数多重说明
@Schema model 层的 JavaBean 描述模型作用及每个属性
@Operation 方法 描述方法作用
@ApiResponse 方法 描述响应状态码等

@Schema: Swagger文档的注解，用于说明类/字段

  • title: 类/字段说明
  • example: 示例，Swagger中会将这个字段作为示例
  • minLength/maxLength: 最小/最大长度，字段为String类型时生效(仅用于文档说明，不会抛出异常)
  • minimum/maximum: 最小/最大值，字段为数字时有效(仅用于文档说明，不会抛出异常)
  • @Tag: 控制器说明
  • name: 名称
  • description: 描述说明
  • @PostMapping: 使用post方法，一般用于新增记录
  • @Operation: 请求说明
  • summary: 说明，Swagger页面在方法后面，不会被折叠
  • descirption: 描述，会被折叠到方法说明中

导入APIfox:

image.png