Springdoc配置参数详解

文章目录

**1. 基础配置**
- **API 文档路径-springdoc.api-docs.path**
- **Swagger UI 路径-springdoc.swagger-ui.path**
- **是否启用 API 文档-springdoc.api-docs.enabled**
- **是否启用 Swagger UI-springdoc.swagger-ui.enabled**
**2. 全局元信息-info**
- **应用标题-springdoc.info.title**
- **应用描述-springdoc.info.description**
- **版本号-pringdoc.info.version**
- **联系人信息-springdoc.info.contact**
- **许可信息-pringdoc.info.license**
**3. 分组与模块化**
- **分组支持-springdoc.group-configs**
- **扫描包范围-springdoc.packages-to-scan**
- **排除特定路径-springdoc.paths-to-exclude**
**4. 安全配置**
- **全局安全方案**
- **全局安全要求**
**5. 自定义行为**
- **缓存控制**
- **排序规则**
- **服务器地址-pringdoc.servers**
**6. 高级配置**
- **自定义 OpenAPI 对象**
- **自定义 Swagger UI**
**7. 总结**

系列文章：
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=john.doe@example.com
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 配置	通过代码方式实现更灵活的定制。