如何将SpringBoot自动生成端点纳入openapi.yml并兼容自定义端点

针对你遇到的「要把SpringBoot自带的Actuator端点（如info、health、prometheus等）纳入openapi.yml维护，但又不想生成重复控制器」的问题，给你几个实用的解决思路：

1. 给自带端点添加生成忽略标记 #

在openapi.yml中给SpringBoot自带的端点配置扩展字段，告诉代码生成工具跳过这些端点的控制器生成。以OpenAPI Generator为例，只需要在对应路径下添加x-codegen-ignore: true：

paths:
  /actuator/health:
    get:
      summary: 系统健康状态检查
      responses:
        '200':
          description: 返回健康状态详情
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
      x-codegen-ignore: true # 关键：让生成工具跳过这个端点的控制器代码
  /actuator/info:
    get:
      summary: 系统信息查询
      responses:
        '200':
          description: 返回系统构建、版本等信息
      x-codegen-ignore: true
  # 自定义端点正常定义，不添加忽略标记
  /api/user/list:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 返回用户列表数据

不同生成工具的扩展字段可能略有差异，比如部分工具用x-skip-codegen，可以查对应工具的文档确认。

2. 在生成插件中配置路径排除 #

如果用Maven或Gradle的OpenAPI生成插件，可以直接在插件配置里指定排除Actuator相关路径，这样即使openapi.yml里包含这些路径，生成时也会跳过。

Maven插件示例： #

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>6.6.0</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <inputSpec>${project.basedir}/src/main/resources/openapi.yml</inputSpec>
        <generatorName>spring</generatorName>
        <excludePaths>/actuator/.*</excludePaths> <!-- 正则匹配排除所有actuator下的端点 -->
        <!-- 其他生成配置 -->
      </configuration>
    </execution>
  </executions>
</plugin>

Gradle插件示例： #

openapiGenerate {
    inputSpec = file('src/main/resources/openapi.yml').path
    generatorName = 'spring'
    excludePaths = [/\/actuator\/.*/]
    // 其他生成配置
}

3. 拆分OpenAPI文档，通过引用整合 #

把Actuator端点的OpenAPI定义单独抽成一个子文档（比如actuator-endpoints.yml），然后在主openapi.yml中通过$ref引用，同时在生成配置里排除这个子文档对应的路径。这样既统一维护了所有端点的文档，又不会生成多余的控制器。

主openapi.yml示例：

openapi: 3.0.3
info:
  title: 系统API文档
  version: 1.0.0
paths:
  # 引用Actuator端点定义
  /actuator/health:
    $ref: './actuator-endpoints.yml#/paths/~1actuator~1health'
  /actuator/info:
    $ref: './actuator-endpoints.yml#/paths/~1actuator~1info'
  # 自定义端点直接定义
  /api/user/list:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功返回用户列表

这种方式适合Actuator端点较多的场景，方便单独维护自带端点的文档内容。

注意事项 #

• 确保openapi.yml里的端点路径和SpringBoot Actuator的实际路径一致（默认前缀是/actuator，可通过management.endpoints.web.base-path配置修改）
• 生成代码前先做本地验证，确认不会生成重复的控制器类
• 团队内部统一规则，明确哪些是自带端点，避免后续误修改

内容的提问来源于stack exchange，提问作者Onisha