配置说明

SpringDoc 提供了丰富的配置选项，本章节将详细介绍如何配置 SpringDoc 以满足各种项目需求。

配置提示

SpringDoc 的配置主要在 application.yml 或 application.properties 文件中进行设置。建议使用 YAML 格式，因为它更易读且支持更复杂的配置结构。

版本兼容性

不同版本的 SpringDoc 对 Spring Boot 版本有特定要求：

SpringDoc 版本	Spring Boot 版本	Java 版本
1.0.3	2.x	8+
2.0.1	3.x	17+

基本配置

以下是 SpringDoc 的常用配置项：

API 文档配置

yaml

springdoc:
  api-docs:
    # 是否开启接口文档
    enabled: true
    # OpenAPI文档的路径
    path: /v3/api-docs

Swagger UI 配置

yaml

springdoc:
  swagger-ui:
    # swagger-ui路径
    path: /swagger-ui.html
    # 持久化认证数据
    persistAuthorization: true
    # 文档展开方式
    docExpansion: none # 可选值: list, full, none
    # 隐藏顶部工具栏和底部信息栏
    displayRequestDuration: true
    # 默认的模型渲染方式
    defaultModelsExpandDepth: -1

文档信息配置

yaml

springdoc:
  info:
    # 标题
    title: '标题：SpringDoc后台管理系统_接口文档'
    # 描述
    description: '描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...'
    # 版本
    version: '版本号: 1.0.0'
    # 作者信息
    contact:
      name: lcz
      email: 1926585708@qq.com
      url: https://gitee.com/hsqyz

安全配置

yaml

springdoc:
  components:
    # 鉴权方式配置
    security-schemes:
      apiKey:
        type: APIKEY
        in: HEADER
        name: Authorization

分组配置

yaml

springdoc:
  # 分组配置
  group-configs:
    - group: SpringDoc项目模块接口文档
      packages-to-scan: com.hsqyz
    - group: 系统管理接口
      packages-to-scan: com.hsqyz.system

完整配置示例

以下是一个完整的配置示例，包含了 SpringDoc 的大部分常用配置：

配置说明

请根据您的实际项目需求调整配置项，特别是 packages-to-scan 路径和 info 信息。

yaml

# SpringDoc OpenAPI 完整配置示例
springdoc:
  # API 文档基础配置
  api-docs:
    # 是否开启接口文档
    enabled: true
    # OpenAPI文档的路径
    path: /v3/api-docs
    # 是否解析Schema属性
    resolve-schema-properties: true
    # 默认请求媒体类型
    default-consumes-media-type: application/json
    # 默认响应媒体类型
    default-produces-media-type: application/json
  
  # Swagger UI 界面配置
  swagger-ui:
    # swagger-ui访问路径
    path: /swagger-ui.html
    # 模型默认展开深度（-1表示全部折叠，1表示展开一层）
    default-models-expand-depth: 1
    # 主要URL名称
    urls-primary-name: JSON
    # 是否启用查询配置
    query-config-enabled: true
    # 持久化认证数据
    persist-authorization: true
    # 文档操作展开方式：none(全部折叠), list(展开列表), full(全部展开)
    doc-expansion: none
    # 显示请求持续时间
    display-request-duration: true
    # 启用深层链接
    deep-linking: true
    # 操作标签排序方式：alpha(字母), method(方法)
    operations-sorter: alpha
    # 标签排序方式：alpha(字母)
    tags-sorter: alpha
    # 禁用默认URL
    disable-swagger-default-url: true
  
  # 是否显示actuator端点
  show-actuator: false
  # 是否使用管理端口
  use-management-port: false
  # 使用默认格式化输出
  writer-with-default-pretty-printer: true
  
  # 文档信息配置
  info:
    # 文档标题
    title: '标题：SpringDoc后台管理系统_接口文档'
    # 文档描述
    description: '描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...'
    # 文档版本
    version: '版本号: 1.0.0'
    # 许可证信息
    license:
      name: MIT
      url: https://opensource.org/licenses/MIT
    # 联系人信息
    contact:
      name: lcz
      email: 1926585708@qq.com
      url: https://gitee.com/hsqyz
  
  # 安全配置
  components:
    security-schemes:
      # API Key 认证
      apiKey:
        type: APIKEY
        in: HEADER
        name: Authorization
      # Basic 认证
      basic:
        type: HTTP
        scheme: basic
      # Bearer Token 认证
      bearer:
        type: HTTP
        scheme: bearer
        bearer-format: JWT
  
  # 默认全局安全配置
  security:
    - apiKey: []
  
  # API 分组配置
  group-configs:
    - group: 'SpringDoc项目模块接口文档'
      packages-to-scan: com.hsqyz
    - group: '用户模块API'
      packages-to-scan: com.hsqyz.user
    - group: '订单模块API'
      packages-to-scan: com.hsqyz.order
    - group: '系统管理API'
      packages-to-scan: com.hsqyz.system

版本特定配置

SpringBoot 2.x + SpringDoc 1.0.3

yaml

# SpringBoot 2.x 版本配置
springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    persistAuthorization: true
  info:
    title: 'SpringDoc API 文档 (SpringBoot 2.x)'
    description: '基于JavaDoc的API文档系统'
    version: '1.0.0'
    contact:
      name: lcz
      email: 1926585708@qq.com
      url: https://gitee.com/hsqyz
  group-configs:
    - group: '默认接口文档'
      packages-to-scan: com.hsqyz

SpringBoot 3.x + SpringDoc 2.0.1

yaml

# SpringBoot 3.x 版本配置
springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    persistAuthorization: true
  info:
    title: 'SpringDoc API 文档 (SpringBoot 3.x)'
    description: '基于JavaDoc的API文档系统'
    version: '2.0.0'
    contact:
      name: lcz
      email: 1926585708@qq.com
      url: https://gitee.com/hsqyz
  group-configs:
    - group: '默认接口文档'
      packages-to-scan: com.hsqyz

版本差异

SpringBoot 3.x 版本主要变化：

需要 Java 17+
包路径从 javax.* 改为 jakarta.*
某些配置项可能有细微差异

JavaDoc 标签支持

SpringDoc 支持以下 JavaDoc 标签，您可以在代码注释中使用这些标签来丰富文档内容：

标签	描述	示例
`@param`	描述方法参数	`@param id 用户ID`
`@return`	描述返回值	`@return 用户对象`
`@throws`	描述可能抛出的异常	`@throws NotFoundException 当用户不存在时`
`@deprecated`	标记为已弃用	`@deprecated 请使用新的API`
`@see`	引用其他类或方法	`@see UserService#getUser`
`@since`	指定引入版本	`@since 1.0.0`
`@version`	版本信息	`@version 1.0.0`

JavaDoc 示例

以下是一个完整的控制器示例，展示了如何使用 JavaDoc 注释来生成丰富的 API 文档：

java

/**
 * 订单管理控制器
 * <p>
 * 提供订单的创建、查询、修改和删除等功能。
 * 支持按条件查询订单和导出订单数据。
 * </p>
 * 
 * @author lcz
 * @version 1.0.0
 * @since 1.0.0
 */
@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderService orderService;

    /**
     * 构造函数注入OrderService
     * 
     * @param orderService 订单服务
     */
    public OrderController(OrderService orderService) {
        this.orderService = orderService;
    }

    /**
     * 分页查询订单列表
     * <p>
     * 支持按订单状态、创建时间等条件筛选订单数据。
     * 结果按创建时间降序排列。
     * </p>
     * 
     * @param status 订单状态，可选值：PENDING, PAID, SHIPPED, COMPLETED, CANCELLED
     * @param startDate 订单创建开始日期，格式：yyyy-MM-dd
     * @param endDate 订单创建结束日期，格式：yyyy-MM-dd
     * @param page 页码，从0开始
     * @param size 每页大小，默认10
     * @return 订单分页数据
     * @throws IllegalArgumentException 当日期格式不正确时
     * @see OrderStatus
     */
    @GetMapping
    public Page<Order> getOrders(
            @RequestParam(required = false) OrderStatus status,
            @RequestParam(required = false) 
            @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate startDate,
            @RequestParam(required = false) 
            @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate endDate,
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "10") int size) {
        
        return orderService.findOrders(status, startDate, endDate, page, size);
    }

    /**
     * 创建新订单
     * <p>
     * 创建一个新的订单，并返回创建成功的订单信息，包含订单ID。
     * </p>
     * 
     * @param orderRequest 订单请求对象，包含商品信息、收货地址等
     * @return 创建成功的订单
     * @throws InvalidOrderException 当订单数据无效时
     * @throws ProductNotFoundException 当商品不存在时
     * @throws StockInsufficientException 当商品库存不足时
     */
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Order createOrder(@RequestBody @Valid OrderRequest orderRequest) {
        return orderService.createOrder(orderRequest);
    }

    /**
     * 获取订单详情
     * <p>
     * 根据订单ID获取订单的详细信息，包括订单项、收货地址、支付信息等。
     * </p>
     * 
     * @param id 订单ID
     * @return 订单详情
     * @throws OrderNotFoundException 当订单不存在时
     */
    @GetMapping("/{id}")
    public OrderDetail getOrderDetail(@PathVariable Long id) {
        return orderService.getOrderDetail(id);
    }

    /**
     * 取消订单
     * <p>
     * 取消指定的订单，仅支持取消未支付的订单。
     * </p>
     * 
     * @param id 订单ID
     * @param reason 取消原因
     * @throws OrderNotFoundException 当订单不存在时
     * @throws OrderStatusException 当订单状态不允许取消时
     * @deprecated 使用 {@link #updateOrderStatus} 方法替代，设置状态为CANCELLED
     */
    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void cancelOrder(
            @PathVariable Long id,
            @RequestParam String reason) {
        
        orderService.cancelOrder(id, reason);
    }

    /**
     * 更新订单状态
     * <p>
     * 更新指定订单的状态，状态变更需要遵循订单状态流转规则。
     * </p>
     * 
     * @param id 订单ID
     * @param status 新的订单状态
     * @return 更新后的订单信息
     * @throws OrderNotFoundException 当订单不存在时
     * @throws OrderStatusException 当状态变更不符合规则时
     * @see OrderStatus
     * @since 1.2.0
     */
    @PatchMapping("/{id}/status")
    public Order updateOrderStatus(
            @PathVariable Long id,
            @RequestParam OrderStatus status) {
        
        return orderService.updateOrderStatus(id, status);
    }
}

最佳实践

确保 JavaDoc 覆盖：对所有控制器、方法、模型类添加完整的 JavaDoc 注释
使用专业术语：在 JavaDoc 中使用专业和一致的术语，提高文档质量
详细描述参数：详细说明每个参数的用途、格式和约束
说明异常情况：使用 @throws 标签说明可能的异常情况
添加示例值：在配置中为复杂参数提供示例值
合理分组：使用分组功能将 API 按模块或功能划分，提高文档可读性
定期更新：随着接口变更及时更新 JavaDoc 注释

进阶配置

自定义 OpenAPI 配置

如果您需要更精细地控制 OpenAPI 配置，可以创建一个配置类：

java

/**
 * SpringDoc OpenAPI 配置类
 */
@Configuration
public class SpringDocConfig {

    /**
     * 自定义 OpenAPI 配置
     */
    @Bean
    public OpenAPICustomizer openAPICustomiser() {
        return openApi -> openApi.addSecurityItem(new SecurityRequirement().addList("bearer-jwt"));
    }

    /**
     * 自定义 API 分组
     */
    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .group("用户API")
                .pathsToMatch("/api/users/**")
                .build();
    }

    /**
     * 自定义 API 分组
     */
    @Bean
    public GroupedOpenApi orderApi() {
        return GroupedOpenApi.builder()
                .group("订单API")
                .pathsToMatch("/api/orders/**")
                .build();
    }
}

自定义全局响应

您可以在 JavaDoc 注释中添加响应说明：

java

/**
 * 创建用户
 * 
 * @param user 用户信息
 * @return 创建的用户信息
 * @response 201 创建成功，返回用户信息
 * @response 400 请求参数错误
 * @response 409 用户名已存在
 */
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public User createUser(@RequestBody @Valid User user) {
    return userService.createUser(user);
}

常见问题解答

Q: SpringDoc 无法生成文档怎么办？

A: 请检查以下几点：

确保已正确配置 JavaDoc 插件（maven-compiler-plugin）
检查 packages-to-scan 配置是否正确
确保控制器类有正确的 JavaDoc 注释
检查 SpringDoc 版本是否与 Spring Boot 版本兼容

Q: 如何自定义文档标题和描述？

A: 在配置文件中修改 springdoc.info 部分：

yaml

springdoc:
  info:
    title: '您的项目标题'
    description: '您的项目描述'
    version: '1.0.0'

Q: 如何配置多个 API 分组？

A: 使用 group-configs 配置多个分组：

yaml

springdoc:
  group-configs:
    - group: '用户模块'
      packages-to-scan: com.example.user
    - group: '订单模块'
      packages-to-scan: com.example.order

Q: 如何添加认证配置？

A: 在 components.security-schemes 中配置认证方式：

yaml

springdoc:
  components:
    security-schemes:
      apiKey:
        type: APIKEY
        in: HEADER
        name: Authorization

Q: 文档界面无法访问怎么办？

A: 检查以下配置：

确保 springdoc.api-docs.enabled=true
检查 springdoc.swagger-ui.path 配置
确认应用已正确启动
检查端口和路径是否正确

Q: 如何隐藏某些接口？

A: 使用 @Hidden 注解或在配置中排除特定路径：

java

@Hidden
@GetMapping("/internal")
public String internalApi() {
    return "internal";
}

Q: 如何自定义响应示例？

A: 在 JavaDoc 注释中添加响应说明：

java

/**
 * 创建用户
 * 
 * @param user 用户信息
 * @return 创建的用户信息
 * @response 201 创建成功，返回用户信息
 * @response 400 请求参数错误
 */
@PostMapping
public User createUser(@RequestBody User user) {
    return userService.createUser(user);
}

最佳实践总结

版本选择：根据 Spring Boot 版本选择合适的 SpringDoc 版本
包扫描：合理配置 packages-to-scan，避免扫描不必要的包
分组管理：使用分组功能将 API 按模块划分，提高可读性
JavaDoc 规范：编写完整、规范的 JavaDoc 注释
配置优化：根据项目需求调整 Swagger UI 配置
安全配置：为需要认证的接口配置合适的安全方案
定期更新：保持 SpringDoc 版本与 Spring Boot 版本同步

配置说明 ​

版本兼容性 ​

基本配置 ​

API 文档配置 ​

Swagger UI 配置 ​

文档信息配置 ​

安全配置 ​

分组配置 ​

完整配置示例 ​

版本特定配置 ​

SpringBoot 2.x + SpringDoc 1.0.3 ​

SpringBoot 3.x + SpringDoc 2.0.1 ​

JavaDoc 标签支持 ​

JavaDoc 示例 ​

最佳实践 ​

进阶配置 ​

自定义 OpenAPI 配置 ​

自定义全局响应 ​

常见问题解答 ​

Q: SpringDoc 无法生成文档怎么办？ ​

Q: 如何自定义文档标题和描述？ ​

Q: 如何配置多个 API 分组？ ​

Q: 如何添加认证配置？ ​

Q: 文档界面无法访问怎么办？ ​

Q: 如何隐藏某些接口？ ​

Q: 如何自定义响应示例？ ​

最佳实践总结 ​

配置说明

版本兼容性

基本配置

API 文档配置

Swagger UI 配置

文档信息配置

安全配置

分组配置

完整配置示例

版本特定配置

SpringBoot 2.x + SpringDoc 1.0.3

SpringBoot 3.x + SpringDoc 2.0.1

JavaDoc 标签支持

JavaDoc 示例

最佳实践

进阶配置

自定义 OpenAPI 配置

自定义全局响应

常见问题解答

Q: SpringDoc 无法生成文档怎么办？

Q: 如何自定义文档标题和描述？

Q: 如何配置多个 API 分组？

Q: 如何添加认证配置？

Q: 文档界面无法访问怎么办？

Q: 如何隐藏某些接口？

Q: 如何自定义响应示例？

最佳实践总结