SpringBoot 项目如何生成 swagger 文档

推荐使用 springdoc-openapi 的理由

1、springdoc-openapi 是 spring 官方出品，与 springboot 兼容更好（springfox 兼容有坑）
2、springdoc-openapi 社区更活跃，springfox 已经 2 年没更新了
3、springdoc-openapi 的注解更接近 OpenAPI 3 规范
官网： springdoc-openapi v2.3.0

使用步骤

第1步：引入依赖

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

第2步：在 Config 中配置描述信息 （可选）

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI springOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("SpringDoc API Test")
                                .description("SpringDoc Simple Application Test")
                                .version("0.0.1"));
    }
}

第3步：在 Controller 中使用注解标记文本

第4步：application.yaml 常用配置

springdoc:
  swagger-ui:
    # 修改Swagger UI路径
    path: /swagger-ui.html
    # 开启Swagger UI界面
    enabled: true
  api-docs:
    # 修改api-docs路径
    path: /v3/api-docs
    # 开启api-docs
    enabled: true
  # 配置需要生成接口文档的扫描包
  packages-to-scan: com.macro.mall.tiny.controller
  # 配置需要生成接口文档的接口路径
  paths-to-match: /brand/**,/admin/**

第5步：调用http://localhost:8081/v3/api-docs

http://localhost:8081/v3/api-docs

参考

拥抱 OpenAPI 3: springdoc-openapi 食用指南
Spring Boot 整合 springdoc-openapi
神器 SpringDoc 横空出世，最适合 SpringBoot 的API文档工具来了~