Swagger 是一个广泛使用的开源工具，专为简化 RESTful API 的设计、文档化、测试和集成而创建。它基于 OpenAPI Specification（以前称为 Swagger Specification），这是一种行业标准，用于定义 REST API 的结构和行为。

引入依赖

<!--swagger-->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.4.0</version>
</dependency>

配置文件

# 配置swagger文档的访问路径
springdoc:
  swagger-ui:
    path: /swagger-ui.html

配置类

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
        .info(new Info().title("标题")
              .description("我的API文档")
              .version("v1")
              .license(new License().name("Apache 2.0").url("http://springdoc.org")))
        .externalDocs(new ExternalDocumentation()
                      .description("外部文档")
                      .url("https://springshop.wiki.github.org/docs"));
    }

}

@SecurityScheme(type = SecuritySchemeType.HTTP, name = "JWT", scheme = "bearer", in = SecuritySchemeIn.HEADER)

@SecurityScheme 注解就是自定义的认证模式，配置请求头携带 token

分组:

@Bean
public GroupedOpenApi userApi() {
    return GroupedOpenApi.builder()
    .group("user")
    .pathsToMatch("/user/**")
    .build();
}
@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
    .group("public")
    .pathsToMatch("/public/**")
    .build();
}

常见注解

@Tag(name="用户操作",description = "用户的一系列操作") 用在 controller 类上
@Operation(summary = "查询所有用户")用在具体方法上
@Parameter(name = "username",description = "测试") 用在具体参数前
@Schema(name = "user",description = "用户表")用在实体类上

访问

http://localhost:8080/swagger-ui/index.html