配置说明

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

基本配置

SpringDoc 的配置主要在 application.yml 或 application.properties 文件中进行设置。以下是常用的配置项：

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 的大部分常用配置：

yaml

# springdoc-openai 配置
springdoc:
  api-docs:
    # 是否开启接口文档
    enabled: true
    # OpenAPI文档的路径
    path: /v3/api-docs
    # 是否使用版本号
    resolve-schema-properties: true
    # 是否开启请求规则
    default-consumes-media-type: application/json
    # 是否开启响应规则
    default-produces-media-type: application/json
  swagger-ui:
    # swagger-ui路径
    path: /swagger-ui.html
    # 模型默认展开深度
    default-models-expand-depth: 1
    # 支持JSON形式访问
    urls-primary-name: JSON
    # 文档查询参数名称
    query-config-enabled: true
    # 持久化认证数据
    persist-authorization: true
    # 文档操作展开方式
    doc-expansion: none # list, full, none
    # 显示请求的持续时间
    display-request-duration: true
    # 深层链接
    deep-linking: true
    # 操作标签是否排序
    operations-sorter: alpha
    # 标签是否排序
    tags-sorter: alpha
    # 禁用默认的URL
    disable-swagger-default-url: true
  # 是否显示actuator端点
  show-actuator: false
  # 是否默认使用tags排序
  use-management-port: false
  # 不返回空引用
  writer-with-default-pretty-printer: true
  # 信息配置
  info:
    # 标题
    title: 'SpringDoc API文档'
    # 描述
    description: '基于JavaDoc的API文档系统'
    # 版本
    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:
      apiKey:
        type: APIKEY
        in: HEADER
        name: Authorization
      basic:
        type: HTTP
        scheme: basic
      bearer:
        type: HTTP
        scheme: bearer
        bearer-format: JWT
  # 默认的全局安全配置
  security:
    - apiKey: []
  # 分组配置
  group-configs:
    - group: '用户模块API'
      packages-to-scan: com.example.user
    - group: '订单模块API'
      packages-to-scan: com.example.order
    - group: '系统管理API'
      packages-to-scan: com.example.system

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);
}

配置说明 ​

基本配置 ​

API 文档配置 ​

Swagger UI 配置 ​

文档信息配置 ​

安全配置 ​

分组配置 ​

完整配置示例 ​

JavaDoc 标签支持 ​

JavaDoc 示例 ​

最佳实践 ​

进阶配置 ​

自定义 OpenAPI 配置 ​

自定义全局响应 ​

配置说明

基本配置

API 文档配置

Swagger UI 配置

文档信息配置

安全配置

分组配置

完整配置示例

JavaDoc 标签支持

JavaDoc 示例

最佳实践

进阶配置

自定义 OpenAPI 配置

自定义全局响应