Springdoc配置参数详解

已于 2025-04-18 15:27:04 修改
阅读量1.2k 收藏 25
点赞数 23
分类专栏： Spring Cloud Alibaba Spring Cloud sprintboot 文章标签： java spring boot Springdoc
于 2025-03-18 13:59:03 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/qq_41694906/article/details/146339981
版权

文章目录


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

1. API 文档基础配置

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

  • springdoc.api-docs.enabled
    • 作用：启用或禁用 OpenAPI 文档生成功能。
    • 默认值：true
    • 效果
      如果设置为 false，将禁用 /v3/api-docs 端点，无法访问 OpenAPI JSON 数据。
    • 示例：
      springdoc.api-docs.enabled=false

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

  • springdoc.api-docs.path
    • 作用：指定 OpenAPI JSON 文档的访问路径。
    • 默认值：/v3/api-docs
    • 效果
      访问路径变为 /openapi.json，例如：http://localhost:8080/openapi.json。
    • 示例：
      springdoc.api-docs.path=/openapi.json

springdoc.api-docs.groups.enabled - 是否启用分组功能，支持多个 API 分组

  • 作用：是否启用分组功能，支持多个 API 分组。

  • 默认值：false

  • 示例：

    springdoc.api-docs.groups.enabled=true

  • 效果：
    启用后，可以通过分组区分不同的 API 文档（如公共 API 和管理员 API）。

2.Swagger UI 配置

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

  • springdoc.swagger-ui.enabled
    • 作用：启用或禁用 Swagger UI。
    • 默认值：true
    • 效果
      如果设置为 false，将禁用 Swagger UI 页面（通常位于 /swagger-ui.html）。
    • 示例：
      springdoc.swagger-ui.enabled=false

尽管 OpenAPI 文档本身已经包含了完整的 API 描述信息，但 Swagger UI 提供了一个更友好的界面，使得开发者可以更方便地浏览和测试 API。以下是一些常见的 Swagger UI 配置及其作用：

Swagger UI 是 OpenAPI 文档的补充工具，它将 API 文档以图形化的方式呈现出来，并提供了交互式功能，极大地方便了开发者的使用。虽然 OpenAPI 文档本身已经足够强大，但 Swagger UI 让文档更加直观、易用。

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

  • springdoc.swagger-ui.path

    • 作用：指定 Swagger UI 的访问路径。

    • 默认值：/swagger-ui.html

    • 效果
      Swagger UI 的访问路径变为 /docs，例如：http://localhost:8080/docs。

    • 示例：

      springdoc.swagger-ui.path=/docs

springdoc.swagger-ui.config-url - 指定自定义的 OpenAPI 配置文件路径。

  • 默认值：无

  • 示例

    springdoc.swagger-ui.config-url=/custom-config.json

  • 效果
    Swagger UI 将加载自定义配置文件 /custom-config.json。

springdoc.swagger-ui.disable-swagger-default-url - 是否禁用默认的 OpenAPI 文档 URL。

  • 默认值：false

  • 示例

    springdoc.swagger-ui.disable-swagger-default-url=true

  • 效果
    禁用后，Swagger UI 不会自动加载默认的 /v3/api-docs URL。

springdoc.swagger-ui.oauth.client-id-配置 OAuth2 客户端 ID

  • 作用：配置 OAuth2 客户端 ID，用于 Swagger UI 的 OAuth2 登录。

  • 默认值：无

  • 示例：

    springdoc.swagger-ui.oauth.client-id=my-client-id
springdoc.swagger-ui.oauth.client-secret=my-secret

  • 效果：
    在 Swagger UI 中显示 OAuth2 登录选项，并使用配置的客户端信息进行认证。

springdoc.swagger-ui.locale - Swagger UI 的界面语言切换为中文

  • 作用：设置 Swagger UI 的语言。

  • 默认值：en

  • 示例：

    springdoc.swagger-ui.locale=zh-CN

  • 效果：
    Swagger UI 的界面语言切换为中文。

3. 全局元信息-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

springdoc.info.contact.name

  • 作用：定义联系人名称。

  • 默认值：无

  • 示例：

    springdoc.info.contact.name=Support Team

  • 效果：
    在生成的 OpenAPI 文档中显示联系人信息。

springdoc.info.contact.email

  • 作用：定义联系人的邮箱地址。

  • 默认值：无

  • 示例：

    springdoc.info.contact.email=support@example.com

  • 效果：
    在生成的 OpenAPI 文档中显示联系人邮箱。

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

springdoc.info.license.name

  • 作用：定义许可证名称。

  • 默认值：无

  • 示例：

    springdoc.info.license.name=Apache 2.0

  • 效果：
    在生成的 OpenAPI 文档中显示许可证信息。

springdoc.info.license.url

  • 作用：定义许可证链接。

  • 默认值：无

  • 示例：

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

  • 效果：
    在生成的 OpenAPI 文档中显示许可证链接。

4. 分组与模块化

springdoc.group-configs - 分组支持

  • springdoc.group-configs
    • 作用：为不同的控制器或包生成独立的 API 文档分组。
    • 示例：
      springdoc.group-configs[0].group=user-api  #定义分组名称。
springdoc.group-configs[0].paths-to-match=/api/user/** #定义分组匹配的路径。
springdoc.group-configs[1].group=order-api
springdoc.group-configs[2].paths-to-match=/api/order/** #定义分组匹配的路径。

springdoc.group-configs[0].group

  • 作用：定义分组名称。

  • 默认值：无

  • 示例：

    springdoc.group-configs[0].group=public

  • 效果：
    创建一个名为 public 的分组。

springdoc.group-configs[0].paths-to-match

  • 作用：定义分组匹配的路径。

  • 默认值：无

  • 示例：

    springdoc.group-configs[0].paths-to-match=/api/public/**

  • 效果：
    仅包含路径匹配 /api/public/** 的 API。

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

  • springdoc.packages-to-scan
    • 作用：指定需要扫描的包范围，用于生成 API 文档。
    • 默认值：当前应用程序的所有包。
    • 效果：
      仅扫描 com.example.api 包中的控制器生成文档。
    • 示例：
      springdoc.packages-to-scan=com.example.api

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

  • springdoc.paths-to-exclude
    • 作用：排除某些路径，不将其包含在生成的 API 文档中。
    • 默认值：无
    • 效果：
      排除所有以 /admin/ 开头的路径。
    • 示例：
      springdoc.paths-to-exclude=/admin/**

5. 安全配置

springdoc.api-docs.security-schemes - 全局安全方案

  • 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
    • 作用：定义全局的安全要求。
    • 示例：
      springdoc.api-docs.security-requirements[0]=ApiKeyAuth

6. springdoc.cache.disabled - 自定义行为

springdoc.cache.disabled - 缓存控制

  • springdoc.cache.disabled
    • 作用：禁用 API 文档的缓存。
    • 默认值：false
    • 效果：
      每次请求都会重新生成 OpenAPI 文档。
    • 示例：
      springdoc.cache.disabled=true

springdoc.default-flat-param-object - 排序规则

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

springdoc.servers - 服务器地址-pringdoc.servers

  • 作用：
    • 定义 OpenAPI 文档中的 servers 字段
      springdoc.servers 允许你在 OpenAPI 文档中显式列出一个或多个服务器地址（URL），并为每个地址添加描述信息。
    • 支持多环境或多网关配置
      如果你的 API 在不同的环境中运行（如开发、测试、生产）或者通过多个网关访问，可以通过 springdoc.servers 配置所有可能的服务器地址。
  • 示例：
    springdoc.servers[0].url=http://localhost:8080
springdoc.servers[0].description=本地开发环境
springdoc.servers[1].url=https://api.example.com
springdoc.servers[1].description=生产环境
  • 效果：
    Swagger UI 会显示一个下拉菜单，列出所有配置的服务器地址。
    开发者可以选择某个服务器地址进行 API 调用。
    适用于多环境或多网关的场景。

springdoc.gatewayUrl - 通过网关使用地址

  • 作用
    • 自动修正 OpenAPI 文档中的服务器地址为网关地址
      当你使用 Spring Cloud Gateway 或其他网关时，客户端实际访问的 API 地址是通过网关路由映射的，而不是后端服务的真实地址。springdoc.gatewayUrl 用于告诉 SpringDoc 客户端应该通过哪个网关地址访问 API。
    • 简化配置
      不需要手动列出多个服务器地址，只需要指定一个网关的基础 URL。
  • 示例
springdoc:
  gatewayUrl: http://gateway.example.com
  • 效果
    • Swagger UI 中的服务器地址会被修正为网关地址（http://gateway.example.com）。
    • API 路径会根据网关的路由规则自动调整（如 /api/v1/example）。
    • 适用于单网关的场景。

对比分析：springdoc.servers vs springdoc.gatewayUrl

特性springdoc.serversspringdoc.gatewayUrl
功能定义 OpenAPI 文档中的 servers 字段，支持多个地址自动修正文档中的服务器地址为网关地址
适用场景多环境（开发、测试、生产）、多网关单网关场景
是否支持多地址支持多个服务器地址只支持一个网关地址
是否需要手动配置路径需要手动配置路径和描述信息自动适配网关的路由规则
优先级如果同时配置了两者，springdoc.servers 优先级更高会被 springdoc.servers 覆盖
  • springdoc.gatewayUrl：适合单网关场景，自动修正服务器地址为网关地址，并适配网关的路由规则。
  • springdoc.servers：适合多环境或多网关场景，允许显式列出多个服务器地址，并为每个地址添加描述信息。
  • 如果需要更灵活的配置，建议使用 springdoc.servers；如果只是简单地适配网关，可以使用 springdoc.gatewayUrl。

7. 高级配置

自定义 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;
}

8. 总结

以下是 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 配置通过代码方式实现更灵活的定制。

9.配置实例

springdoc:
  api-docs:
    enabled: true
    path: /openapi.json
    groups:
      enabled: true
  swagger-ui:
    enabled: true
    path: /docs
    config-url: /custom-config.json
    disable-swagger-default-url: false
    oauth:
      client-id: my-client-id
      client-secret: my-secret
    locale: zh-CN
  info:
    title: User API
    description: API for managing users
    version: 1.0
    contact:
      name: Support Team
      email: support@example.com
    license:
      name: Apache 2.0
      url: https://www.apache.org/licenses/LICENSE-2.0.html
  group-configs:
    - group: public
      paths-to-match: /api/public/**
    - group: admin
      paths-to-match: /api/admin/**
  packages-to-scan: com.example.api
  paths-to-exclude: /internal/**
  oauth2:
    client-id: oauth-client-id
    client-secret: oauth-client-secret
  cache:
    disabled: false
  writer-with-default-pretty-printer: true
Swagger API 文档 | SpringDoc 配置项
甘蓝的专栏
04-12 2463
介绍SpringDoc及Swagger UI配置项。
SpringDoc使用
m0_64132144的博客
11-13 1104
SpringDoc是一款可以结合SpringBoot使用的API文档生成工具，基于OpenAPI 3，目前在Github上已有2.9K+Star，更新发版还是挺勤快的，是一款更好用的Swagger库！值得一提的是SpringDoc不仅支持Spring WebMvc项目，还可以支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目，总之非常强大，下面是一张SpringDoc的架构图。
01_学习springdoc的基本使用
热门推荐
ShiJunzhiCome的博客
02-01 1万+
网上冲浪🏄🏻‍♂️时，无意间发现 java web 应用程序的在线接口文档，除了耳熟能详的 swagger 之外，还有个 springdoc。这也许就叫惊喜( ͡• ͜ʖ ͡• )还记得要使用 swagger2 的话，springboot 项目里面需要引入 springfox 的依赖。swagger2 遵循的是 OpenAPI 2 规范。现在已经有了 OpenAPI 3 规范，springdoc 便是 OpenAPI 3 和 springboot 的结合，是 springfox 的完美替代品。
Spring Boot 3 + SpringDoc：打造接口文档
最新发布
weixin_46619605的博客
04-18 1265
Spring Boot 3 + SpringDoc：打造接口文档
Spring Boot配置Springdoc
qq_37759895的博客
06-25 560
刚刚开通了一个公众号，会分享一些技术博客和自己觉得比较好的项目，同时会更新一些自己使用的工具和图书资料，后面会整理一些面试资料进行分享，觉得有兴趣的可以关注一下。
配置springdoc
qq_43187580的博客
09-12 2274
springfox 替换成 springdoc
spring配置全书.doc
03-29
Spring配置全书 关于Spring的配置 Spring Framework总是不断的改变着Java企业开发的方向，它用一种松耦合的方式来配置和组装应用程序对象和业务对象，比以往的Java企业开发来的更加简洁。一旦你开发了基于Spring的应用程序，在Spring上下文配置的那些资源简直就是唾手可得。 依赖注入是Spring容器的核心 尽管Spring Framework可以做很多事，但依赖注入却是Spring容器提供的最基本的功能。 任何稍微复杂一点的应用程序都至少由两个或两个以上的对象协作在一起，共同完成一些业务逻辑。以往的Java企业开发，每个对象都要自己去主动获得他们所引用（或依赖）的对象，才可正常运作。这将导致代码之间的紧耦合，难以测试。 .....
基于SpringBoot3从零配置SpringDoc
????
02-19 3716
详细讲解了如何使用 SpringDoc 生成应用的 API 文档。
springdoc配置
04-02
为了让 `springdoc-openapi` 正确解析 RESTful 接口并生成对应的文档，可以在控制器层添加必要的注解。例如： ```java import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations....
Spring整合配置文件详解.doc
10-22
### Spring整合配置文件详解 #### 一、Spring框架概述 Spring框架是一个开源的Java平台，提供了全面的基础架构支持，让开发者能够轻松构建企业级应用程序。它最初由Rod Johnson创建，并于2004年发布了第一个版本。...
Spring doc 文档
07-30
Spring doc 文档
SpringDoc和Swagger使用
egekm_sefg的博客
01-21 1035
Swagger和Springdoc是两个常用的工具，用于生成和维护API文档，特别是针对基于REST的Web服务。它们有效地提升了API的可读性和可维护性，帮助开发者、产品经理和其他利益相关者更好地理解和使用所提供的API。注意：Swagger支持springboot2.0但不支持springboot3.0。
Spring-doc-openapi3实用配置
catcher92的博客
07-20 8892
1.配置swagger使用jwt 可以通过编程式实现，也可以通过注解式实现，我这里拿注解式举例 @SpringBootConfiguration @OpenAPIDefinition(info = @Info(title = "API", version = "v1")) @SecurityScheme( name = "token", type = SecuritySchemeType.HTTP, bearerFormat = "JWT",
SpringDoc基础配置和集成OAuth2登录认证教程
云逸的博客
11-20 1633
现在大部分教程是在swagger-ui页面添加一个请求头，使用时先去获取一个token，然后再将获取的token填充至页面的token输入框内，如果是通过某个接口自己生成token的方式使用这种配置没什么太大问题，但是如果是通过OAuth2登录获取token时就比较麻烦，要填充token type和access token，所以在swagger-ui提供的页面中提供OAuth2登录的入口，OAuth2登录自动配置，一步到位。
spring的常见配置
cold__liang的博客
05-19 515
由于每次在搭建项目的时候，都需要写各种配置，包括xml依赖配置，yml配置，有时候一些基本的注解也需要重复调用，但是碍于本人实在是懒得记，都是复制粘贴于上一个项目，这样还是感觉不太好，所以打算总结一些有哪些常见的配置文件的写法。
SpringBoot集成SpringDoc，配置文档权限校验
一只猿Hou的博客
01-14 2723
近来颇为懈怠，博客竟两月有余未发一篇，惭愧惭愧。值此端午佳节（dragon boat festival）作为调包高手、API小王子的我就聊聊API文档的那些事吧，如果你也是API小王子，那我们就可以在一起欢度佳节了，哈哈...我惯用Java，惯用Spring，所以这里谈论的是关于springboot中如何处理文档的内容。
springboot---配置文件
lipviolet的博客
03-02 6827
Springboot中配置文件配置大全 转载于：https://blog.youkuaiyun.com/zhuzhezhuzhe1/article/details/80560306 配置 ############################################################# # mvc ############################################################# spring.mvc.async.request-timeout=
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

苍煜

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值