Springdoc配置参数详解

系列文章：
springboot-swagger详解
springboot-优美的Knife4j文档-Swagger进化
Spring Cloud Gateway 网关整合 Knife4j
SpringBoot之如何集成SpringDoc最详细文档

1. 基础配置

API 文档路径-springdoc.api-docs.path

• springdoc.api-docs.path
  • 作用：指定 OpenAPI JSON 文档的访问路径。
  • 默认值：/v3/api-docs
  • 示例：

    springdoc.api-docs.path=/openapi
    

Swagger UI 路径-springdoc.swagger-ui.path

• springdoc.swagger-ui.path
  • 作用：指定 Swagger UI 的访问路径。
  • 默认值：/swagger-ui.html
  • 示例：

    springdoc.swagger-ui.path=/docs
    

是否启用 API 文档-springdoc.api-docs.enabled

• springdoc.api-docs.enabled
  • 作用：启用或禁用 OpenAPI 文档生成功能。
  • 默认值：true
  • 示例：

    springdoc.api-docs.enabled=false
    

是否启用 Swagger UI-springdoc.swagger-ui.enabled

• springdoc.swagger-ui.enabled
  • 作用：启用或禁用 Swagger UI。
  • 默认值：true
  • 示例：

    springdoc.swagger-ui.enabled=false
    

---

2. 全局元信息-info

应用标题-springdoc.info.title

• springdoc.info.title
  • 作用：设置 API 文档的标题。
  • 默认值：空
  • 示例：

    springdoc.info.title=用户管理系统
    

应用描述-springdoc.info.description

• springdoc.info.description
  • 作用：设置 API 文档的描述信息。
  • 默认值：空
  • 示例：

    springdoc.info.description=用户管理相关的 API 文档
    

版本号-pringdoc.info.version

• springdoc.info.version
  • 作用：设置 API 文档的版本号。
  • 默认值：空
  • 示例：

    springdoc.info.version=1.0.0
    

联系人信息-springdoc.info.contact

• springdoc.info.contact.name
• springdoc.info.contact.email
• springdoc.info.contact.url
  • 作用：设置文档的联系人信息（姓名、邮箱、URL）。
  • 默认值：空
  • 示例：

    springdoc.info.contact.name=John Doe
    springdoc.info.contact.email=[e-mail]
    springdoc.info.contact.url=http://example.com
    

许可信息-pringdoc.info.license

• springdoc.info.license.name
• springdoc.info.license.url
  • 作用：设置文档的许可证信息（名称、URL）。
  • 默认值：空
  • 示例：

    springdoc.info.license.name=Apache 2.0
    springdoc.info.license.url=https://www.apache.org/licenses/LICENSE-2.0
    

---

3. 分组与模块化

分组支持-springdoc.group-configs

• springdoc.group-configs
  • 作用：为不同的控制器或包生成独立的 API 文档分组。
  • 示例：

    springdoc.group-configs[0].group=user-api
    springdoc.group-configs[0].packages-to-scan=com.example.user
    springdoc.group-configs[1].group=order-api
    springdoc.group-configs[1].packages-to-scan=com.example.order
    

扫描包范围-springdoc.packages-to-scan

• springdoc.packages-to-scan
  • 作用：指定需要扫描的包范围，用于生成 API 文档。
  • 默认值：当前应用程序的所有包。
  • 示例：

    springdoc.packages-to-scan=com.example.api
    

排除特定路径-springdoc.paths-to-exclude

• springdoc.paths-to-exclude
  • 作用：排除某些路径，不将其包含在生成的 API 文档中。
  • 默认值：无
  • 示例：

    springdoc.paths-to-exclude=/admin/**
    

---

4. 安全配置

全局安全方案

• springdoc.api-docs.security-schemes
  • 作用：定义全局的安全方案（如 OAuth2、API Key 等）。
  • 示例：

    springdoc.api-docs.security-schemes[0].name=ApiKeyAuth
    springdoc.api-docs.security-schemes[0].type=apiKey
    springdoc.api-docs.security-schemes[0].in=header
    

全局安全要求

• springdoc.api-docs.security-requirements
  • 作用：定义全局的安全要求。
  • 示例：

    springdoc.api-docs.security-requirements[0]=ApiKeyAuth
    

---

5. 自定义行为

缓存控制

• springdoc.cache.disabled
  • 作用：禁用 API 文档的缓存。
  • 默认值：false
  • 示例：

    springdoc.cache.disabled=true
    

排序规则

• springdoc.default-flat-param-object
  • 作用：是否将参数对象展平为单个参数。
  • 默认值：false
  • 示例：

    springdoc.default-flat-param-object=true
    

服务器地址-pringdoc.servers

• springdoc.servers
  • 作用：定义 API 的服务器地址列表。
  • 示例：

    springdoc.servers[0].url=http://localhost:8080
    springdoc.servers[0].description=本地开发环境
    springdoc.servers[1].url=https://api.example.com
    springdoc.servers[1].description=生产环境
    

---

6. 高级配置

自定义 OpenAPI 对象

• 作用：通过 Java 配置类自定义 OpenAPI 对象。
• 示例：

  @Bean
  public OpenAPI customOpenAPI() {
      return new OpenAPI()
          .info(new Info()
              .title("用户管理系统")
              .version("1.0")
              .description("用户管理相关的 API 文档"))
          .addServersItem(new Server().url("http://localhost:8080").description("本地开发环境"));
  }
  

自定义 Swagger UI

• 作用：通过 Java 配置类自定义 Swagger UI 行为。
• 示例：

  @Bean
  public SwaggerUiConfigProperties swaggerUiConfig() {
      SwaggerUiConfigProperties config = new SwaggerUiConfigProperties();
      config.setPath("/custom-docs");
      return config;
  }
  

---

7. 总结

以下是 springdoc 配置参数的分类总结：

类别	参数	作用
基础配置	springdoc.api-docs.path, springdoc.swagger-ui.path, springdoc.api-docs.enabled	配置 API 文档路径、Swagger UI 路径及启用状态。
全局元信息	springdoc.info.title, springdoc.info.description, springdoc.info.version	设置 API 文档的标题、描述、版本等基本信息。
分组与模块化	springdoc.group-configs, springdoc.packages-to-scan, springdoc.paths-to-exclude	支持分组、限制扫描范围、排除特定路径。
安全配置	springdoc.api-docs.security-schemes, springdoc.api-docs.security-requirements	定义全局安全方案和要求。
自定义行为	springdoc.cache.disabled, springdoc.default-flat-param-object, springdoc.servers	控制缓存、参数对象展平、服务器地址等高级功能。
高级配置	自定义 OpenAPI 对象、Swagger UI 配置	通过代码方式实现更灵活的定制。