尧图网页设计 
运维任务调度后端【免费下载链接】rundeckEnable Self-Service Operations: Give specific users access to your existing tools, services, and scripts项目地址https://gitcode.com/gh_mirrors/ru/rundeck点击查看免费下载Rundeck 的 API 端点必须遵循统一的 OpenAPI 文档规范、严格的版本化规则与先测试后实现的开发流程。本文以仓库内.claude/skills/create-api-endpoint/SKILL.md为骨架结合.claude/docs/api-guidelines.md、.claude/docs/testing-guidelines.md以及rundeckapp中真实的版本管理源码与构建脚本完整讲解如何在 Rundeck 中新增、修改并发布一个带版本号的 REST API 端点。读完本文你将掌握从 API 设计、Spock 测试先行、DTO 与控制器注解到 OpenAPI 规范生成与验证的完整落地方法。何时使用本 Skillcreate-api-endpoint是 Rundeck 仓库内为开发者提供的 API 端点创建技能Skill其适用场景非常明确创建全新的 REST API 端点修改现有的 API 端点需要补充 OpenAPI 规范注解需要满足 API 版本化要求。在动手之前Skill 要求开发者先阅读三份配套规范文档作为上下文与行为准则.claude/docs/api-guidelines.md— 完整的注解指南.claude/docs/development-guidelines.md— API 版本化与文档要求.claude/docs/testing-guidelines.md— API 测试要求。总体流程八个阶段Rundeck API 端点开发遵循一个固定的八阶段流水线从加载上下文到更新官方文档每一步都有明确的产出物Phase 1 Load Context读取三份规范文档Phase 2 Design API确定 HTTP 方法、URL 路径、DTO、API 版本与认证要求Phase 3 Write API Tests First先写测试TDD验证新旧版本行为差异Phase 4 Create/Update DTOs创建带Schema注解的数据传输对象Phase 5 Create/Update Controller编写带完整 OpenAPI 注解的控制器Phase 6 Update build.gradle为新插件声明 OpenAPI 依赖与目标文件Phase 7 Run Tests and Verify运行测试并验证生成的 OpenAPI 规范Phase 8 Update Documentation同步更新 Rundeck 官方 API 文档与版本历史。Phase 1–2API 设计与版本化规则设计输入设计阶段需要明确四个要素HTTP 方法GET / POST / PUT / DELETEURL 路径必须以/api/$VERSION/...开头请求/响应 DTO用独立类表达数据结构API 版本新行为必须提升版本号认证要求明确端点所需的授权如Authorization required: create for job resource type。API 版本化规则版本化是 Rundeck API 的硬性约定规则如下变更类型版本策略新功能New functionality提升为新 API 版本新端点New endpoint提升为新 API 版本修改现有端点Modified endpoint提升为新 API 版本缺陷修复Bug fix保持同一 API 版本这意味着向后兼容只适用于缺陷修复任何新行为都不允许偷偷塞进旧版本中旧版本客户端必须仍然按照旧语义工作。源码佐证版本号如何定义与使用Rundeck 的 API 版本号集中定义在 ApiVersions.groovy 中。该文件从V14一直声明到V60并给出当前版本配置// References the current API version public final static int API_CURRENT_VERSION V60 // Hardcoded inline string constant for the current version used in API doc generation public final static String API_CURRENT_VERSION_STR 60 public final static int API_EARLIEST_VERSION V14 public final static int API_DEPRECATION_VERSION V17文件中还通过反射机制API_VERSION_VARIABLE_NAME_PATTERN /\bV\d\b/自动收集所有V\d形式的字段生成受支持的版本列表Versions——这意味着新增版本只需在文件顶部按约定追加一个常量并同步更新Current API version Configuration两行即可。版本判断发生在实际请求处理层。例如在 ApiController.groovy 中代码通过request.api_version与版本常量比较来决定行为分支boolean tokenRolesV19Enabled request.api_version ApiVersions.V19 boolean tokensV37 request.api_version ApiVersions.V37这就是版本化规则在运行时落地的方式每个新版本行为都必须在代码里以request.api_version ApiVersions.Vxx这样的条件显式隔离确保旧版本请求走旧逻辑。Phase 3先写测试TDD 先行Rundeck 的 API 测试要求非常明确测试必须先于实现编写并且必须同时验证新版本与旧版本的行为差异。测试需求有四条硬性标准✅ 新行为在新API 版本下正常工作❌ 新行为在旧API 版本下不工作返回 404 或对应错误✅ 错误条件返回正确的响应✅ 成功条件在全部调用模式下正常工作。标准测试形态Skill 文档给出的 Spock 测试模板如下def should return projects for API v44() { when: def response client.get(/api/44/projects) then: response.status 200 response.json.size() 0 } def should reject for API v43() { when: def response client.get(/api/43/projects) then: response.status 404 // or appropriate error }这个模板体现了正反验证思想同一端点、相邻两个版本一个断言可用、一个断言被拒绝从而锁死新行为的版本边界。测试规范与仓库实测根据.claude/docs/testing-guidelines.mdAPI 测试使用Testcontainers Spock组合位于functional-test/目录。仓库中已有大量此类真实测试例如 ConfigSpec.groovy它通过APITest注解标记、继承BaseContainer获取测试容器客户端并直接以doPost(/projects, testProperties)的方式调用 API。测试断言同样覆盖错误条件与边界场景例如对项目配置键的 JSON 读写验证ConfigSpec.groovy。备注functional-test/src/test/groovy/org/rundeck/tests/functional/api/job/JobServerUrlSpec.groovy等测试中还直接出现/api/50/projects这类硬编码版本路径说明测试代码与版本常量同样需要随版本演进同步维护。Phase 4DTO 与Schema注解DTO数据传输对象是请求与响应数据结构的载体必须使用独立的数据类而非内联 Schema 定义。这样做的好处包括编译期类型安全、OpenAPI 规范直接从代码结构自动生成、DTO 变更自动同步到规范避免规范与代码漂移。DTO 编写模板Schema(description Project response) class ProjectResponse { Schema(description Project name, example MyProject) String name Schema(description Project description) String description Schema(description Creation date, example 2025-01-01T00:00:00Z) String created }字段级Schema应尽量提供description与example。根据 api-guidelines.md 的补充建议请求 DTO 还应标记required true并配合CompileStatic使用CompileStatic Schema(description Request to create a new user) class CreateUserRequest { Schema(description Username, required true, example johndoe) String username Schema(description Password, required true) String password Schema(description User roles, required true) ListString roles }在注解中引用 DTO规范强烈推荐用Schema(implementation ClassName)引用 DTO而不是手写type objectrequiredProperties的内联对象定义ApiResponse( responseCode 201, description User created successfully, content Content( mediaType MediaType.APPLICATION_JSON, schema Schema(implementation UserCreatedResponse) ) )配合控制器方法的Body参数可以实现类型安全的请求绑定def apiCreate(Body CreateUserRequest request) { // Access properties with type safety: request.username, request.password }Phase 5控制器与端点注解核心实操控制器是端点实现的载体注解分三个层级类级Controller、方法级Operation/Tag/Response、参数级Parameters/Body。Step 1类级Controller注解必填。没有Controller方法上的所有注解都不会出现在生成的 OpenAPI 规范中。Controller(value /api/44) class ProjectController { // ... }value参数可以指定整个控制器所有端点的统一基路径例如/api/44/projects方法注解里的uri再写相对路径。Step 2方法级注解只读端点GETOperation( method GET, summary List Projects, description Returns a list of all projects accessible to the user ) Tag(name Project) ApiResponse( responseCode 200, description Project list successfully retrieved, content Content( mediaType application/json, schema Schema(implementation ProjectListResponse.class) ) ) Get(uri /projects, produces MediaType.APPLICATION_JSON) def listProjects() { // implementation }带请求体POST/PUT通过Operation.requestBody描述请求体同时配合Post/PutOperation( method POST, summary Create Project, description Creates a new project with the specified configuration, requestBody RequestBody( description Project configuration, content Content( mediaType application/json, schema Schema(implementation ProjectCreateRequest.class) ), required true ) ) ApiResponse( responseCode 201, description Project created successfully, content Content( mediaType application/json, schema Schema(implementation ProjectResponse.class) ) ) Post(uri /projects) def createProject() { // implementation }查询/路径参数使用Parameters([...])数组路径参数用ParameterIn.PATH查询参数用ParameterIn.QUERYParameters([ Parameter( name project, in ParameterIn.PATH, description Project name, required true, schema Schema(type string) ), Parameter( name includeArchived, in ParameterIn.QUERY, description Include archived items, schema Schema(type boolean, defaultValue false) ) ]) Get(uri /project/{project}/jobs) def getProjectJobs() { // implementation }关于Operation.description的写作要求不要写Get data或Update resource这类通用描述。规范的描述应当说明端点的业务目的期望的输入/输出行为在整体工作流中的集成上下文副作用或重要注意事项授权要求与 API 版本信息例如 Authorization required:createforjobresource type — Since: v46。关于Tag的规范Tag 是 OpenAPI 文档的归类维度Rundeck 有严格的约定大小写规范使用规范定义的标准 Tag禁止小写用Jobs而非jobs每端点只能一个 Tag要么Tag(name Project)要么在Operation中写tags [Project]禁止tags [Project, Configuration]这种多 Tag 写法标准 Tag 参考表来自 api-guidelines.mdTag用途ACL访问控制列表操作Calendars日历管理操作Configuration配置管理操作Health健康检查操作Jobs任务管理操作System系统操作User用户管理操作WebhookWebhook 操作Phase 6build.gradle 依赖与 OpenAPI 目标文件新端点所在的模块需要声明 Micronaut OpenAPI 与 Swagger 注解依赖。版本号统一由gradle.properties中的属性集中管理compileOnly io.micronaut.openapi:micronaut-openapi:${micronautOpenapiVersion} implementation io.swagger.core.v3:swagger-annotations:${swaggerVersion}根据 api-guidelines.md完整依赖清单还包含implementation io.micronaut:micronaut-http-server:${micronautVersion} implementation io.micronaut:micronaut-inject:${micronautVersion} implementation io.micronaut:micronaut-inject-java:${micronautVersion} implementation io.micronaut:micronaut-inject-groovy:${micronautVersion} implementation io.micronaut:micronaut-core:${micronautVersion}新插件声明独立的目标文件OpenAPI 规范由compileGroovy任务触发 Micronaut 注解处理器生成。每个插件必须声明唯一的 target filerundeckapp再通过 additional files 机制合并各插件的规范。目标文件配置模板tasks.withType(GroovyCompile) { def target new File( project.rootDir, rundeckapp/build/openapi/${project.name}.yml ).absolutePath configure(groovyOptions) { forkOptions.jvmArgs [ -Xmx1024m, -Dmicronaut.openapi.target.file${target}.toString() ] } }源码佐证rundeckapp 的规范后处理在 rundeckapp/build.gradle 中有一个专门的fixOpenApiSpec任务L590-L631它读取编译产物build/classes/groovy/main/META-INF/swagger/rundeck-api.yml并从ApiVersions.groovy中正则提取API_CURRENT_VERSION_STR的值把规范中$API_VERSION$占位符替换为真实版本号。这印证了两点OpenAPI 规范的最终产物路径是rundeckapp/build/classes/groovy/main/META-INF/swagger/rundeck-api.yml版本号字符串的单一事实来源就是ApiVersions.groovy中的API_CURRENT_VERSION_STR改动它会影响规范生成结果。Phase 7运行测试与验证Skill 文档给出的验证命令如下# API 测试 ./gradlew :functional-test:apiTest # 验证 OpenAPI 规范已生成 ls rundeckapp/build/classes/groovy/main/META-INF/swagger/rundeck-*.yml # 全量测试套件 ./gradlew test注意验证清单中的关键检查点构建后确认 YAML 生成于rundeckapp/build/classes/groovy/main/META-INF/swagger/目录确认 OpenAPI 规范包含新增端点确认旧版本 API 测试仍通过、新版本测试通过。Phase 8更新官方文档任何 API 变更都必须同步文档Skill 明确列出三项更新 Rundeck 官方 API 参考文档更新 API 版本历史Version History记录变更如果是新 API 版本说明新增/改动了什么内容。注解速查表类级注解说明Controller(value /api/44/base-path)必填。Micronaut 控制器可指定基路径缺失时方法不会出现在规范中方法级注解说明Get / Post / Put / Delete(uri /path)必填。HTTP 方法绑定Operation(...)必填。OpenAPI 操作定义summary / description / requestBodyTag(name Category)必填。分组归类或Operation(tags [Category])仅限一个ApiResponse(...)必填。响应定义responseCode / description / contentParameters([...])可选。查询/路径参数声明数据类型注解说明Schema(...)必填。用于 DTO 类与字段定义数据结构交付 Checklist设计阶段API 设计已评审HTTP 方法、路径、版本化新功能已提升 API 版本build.gradle已添加 Micronaut/Swagger 依赖新插件已配置 OpenAPI 目标文件控制器已用Controller注解每个方法都有Get/Post/Put/Delete每个方法都有带详细描述的Operation每个方法恰好一个 TagTag(name X)或Operation中tags [X]每个方法都有ApiResponsePOST/PUT 已声明请求体需要时已声明参数数据类型DTO 类已注解SchemaDTO 字段已注解Schema测试API 测试先行TDD测试验证新 API 版本可用测试验证旧 API 版本不支持新行为API 测试全部通过验证构建并验证rundeckapp/build/classes/groovy/main/META-INF/swagger/下 YAML 已生成OpenAPI 规范包含新增端点Rundeck 官方文档已更新常见错误与纠正❌ 禁止忘记Controller注解方法不会出现在规范中新功能却使用旧 API 版本跳过 API 版本测试DTO 遗漏Schema忘记更新 Rundeck 官方文档。✅ 必须始终使用Controller新行为必须提升 API 版本新旧两个 API 版本都要测试完整注解所有 DTO更新官方文档。延伸阅读.claude/skills/create-api-endpoint/SKILL.md— 本文的原始 Skill 定义.claude/docs/api-guidelines.md— 完整注解指南与标准 Tag 表.claude/docs/testing-guidelines.md— 测试哲学与 API 测试要求ApiVersions.groovy — API 版本常量与当前版本配置的单一事实来源ApiController.groovy — 版本条件分支的真实使用示例rundeckapp/build.gradle —fixOpenApiSpec任务与规范生成后处理逻辑ConfigSpec.groovy — Testcontainers Spock 的功能性 API 测试实例。结合上述源码可以确认Rundeck 的 API 端点开发是一套版本常量集中管理、行为按版本条件隔离、测试正反双向验证、注解驱动规范生成的完整体系。遵循create-api-endpointSkill 的八阶段流程就能以可预期、可验证、可回溯的方式为 Rundeck 贡献新的 REST API 端点。赞分享运维任务调度后端【免费下载链接】rundeckEnable Self-Service Operations: Give specific users access to your existing tools, services, and scripts项目地址https://gitcode.com/gh_mirrors/ru/rundeck点击查看免费下载相关推荐Rundeck API 开发规范基于 Grails Controller 与 Micronaut OpenAPI 注解的规格生成实战指南Rundeck API 开发规范基于 Grails Controller 与 Micronaut OpenAPI 注解的规格生成实战指南 本文是 Rundec运维任务调度后端OptiScaler 超采样替换 3 步上手免费启用帧生成与画质调校OptiScaler 超采样替换 3 步上手免费启用帧生成与画质调校 OptiScaler 是一个开源的超采样替换与帧生成工具它以 DLL 注入的方式把你图形学游戏开发Rundeck 后端测试实战指南基于 create-test 技能编写 Spock 单元测试与 Testcontainers API/功能测试Rundeck 后端测试实战指南基于 create test 技能编写 Spock 单元测试与 Testcontainers API/功能测试 本篇技术指南围运维任务调度后端上一篇显卡驱动卸载不干净怎么办DDU 免费开源工具彻底清理驱动的完整手册下一篇深入 mamba::solverMamba 包求解器通用接口与 LibSolv 实现全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rundeck REST API 端点开发实战指南：基于 create-api-endpoint Skill 的 OpenAPI 注解、版本管理与测试规范
运维任务调度后端【免费下载链接】rundeckEnable Self-Service Operations: Give specific users access to your existing tools, services, and scripts项目地址https://gitcode.com/gh_mirrors/ru/rundeck点击查看免费下载Rundeck 的 API 端点必须遵循统一的 OpenAPI 文档规范、严格的版本化规则与先测试后实现的开发流程。本文以仓库内.claude/skills/create-api-endpoint/SKILL.md为骨架结合.claude/docs/api-guidelines.md、.claude/docs/testing-guidelines.md以及rundeckapp中真实的版本管理源码与构建脚本完整讲解如何在 Rundeck 中新增、修改并发布一个带版本号的 REST API 端点。读完本文你将掌握从 API 设计、Spock 测试先行、DTO 与控制器注解到 OpenAPI 规范生成与验证的完整落地方法。何时使用本 Skillcreate-api-endpoint是 Rundeck 仓库内为开发者提供的 API 端点创建技能Skill其适用场景非常明确创建全新的 REST API 端点修改现有的 API 端点需要补充 OpenAPI 规范注解需要满足 API 版本化要求。在动手之前Skill 要求开发者先阅读三份配套规范文档作为上下文与行为准则.claude/docs/api-guidelines.md— 完整的注解指南.claude/docs/development-guidelines.md— API 版本化与文档要求.claude/docs/testing-guidelines.md— API 测试要求。总体流程八个阶段Rundeck API 端点开发遵循一个固定的八阶段流水线从加载上下文到更新官方文档每一步都有明确的产出物Phase 1 Load Context读取三份规范文档Phase 2 Design API确定 HTTP 方法、URL 路径、DTO、API 版本与认证要求Phase 3 Write API Tests First先写测试TDD验证新旧版本行为差异Phase 4 Create/Update DTOs创建带Schema注解的数据传输对象Phase 5 Create/Update Controller编写带完整 OpenAPI 注解的控制器Phase 6 Update build.gradle为新插件声明 OpenAPI 依赖与目标文件Phase 7 Run Tests and Verify运行测试并验证生成的 OpenAPI 规范Phase 8 Update Documentation同步更新 Rundeck 官方 API 文档与版本历史。Phase 1–2API 设计与版本化规则设计输入设计阶段需要明确四个要素HTTP 方法GET / POST / PUT / DELETEURL 路径必须以/api/$VERSION/...开头请求/响应 DTO用独立类表达数据结构API 版本新行为必须提升版本号认证要求明确端点所需的授权如Authorization required: create for job resource type。API 版本化规则版本化是 Rundeck API 的硬性约定规则如下变更类型版本策略新功能New functionality提升为新 API 版本新端点New endpoint提升为新 API 版本修改现有端点Modified endpoint提升为新 API 版本缺陷修复Bug fix保持同一 API 版本这意味着向后兼容只适用于缺陷修复任何新行为都不允许偷偷塞进旧版本中旧版本客户端必须仍然按照旧语义工作。源码佐证版本号如何定义与使用Rundeck 的 API 版本号集中定义在 ApiVersions.groovy 中。该文件从V14一直声明到V60并给出当前版本配置// References the current API version public final static int API_CURRENT_VERSION V60 // Hardcoded inline string constant for the current version used in API doc generation public final static String API_CURRENT_VERSION_STR 60 public final static int API_EARLIEST_VERSION V14 public final static int API_DEPRECATION_VERSION V17文件中还通过反射机制API_VERSION_VARIABLE_NAME_PATTERN /\bV\d\b/自动收集所有V\d形式的字段生成受支持的版本列表Versions——这意味着新增版本只需在文件顶部按约定追加一个常量并同步更新Current API version Configuration两行即可。版本判断发生在实际请求处理层。例如在 ApiController.groovy 中代码通过request.api_version与版本常量比较来决定行为分支boolean tokenRolesV19Enabled request.api_version ApiVersions.V19 boolean tokensV37 request.api_version ApiVersions.V37这就是版本化规则在运行时落地的方式每个新版本行为都必须在代码里以request.api_version ApiVersions.Vxx这样的条件显式隔离确保旧版本请求走旧逻辑。Phase 3先写测试TDD 先行Rundeck 的 API 测试要求非常明确测试必须先于实现编写并且必须同时验证新版本与旧版本的行为差异。测试需求有四条硬性标准✅ 新行为在新API 版本下正常工作❌ 新行为在旧API 版本下不工作返回 404 或对应错误✅ 错误条件返回正确的响应✅ 成功条件在全部调用模式下正常工作。标准测试形态Skill 文档给出的 Spock 测试模板如下def should return projects for API v44() { when: def response client.get(/api/44/projects) then: response.status 200 response.json.size() 0 } def should reject for API v43() { when: def response client.get(/api/43/projects) then: response.status 404 // or appropriate error }这个模板体现了正反验证思想同一端点、相邻两个版本一个断言可用、一个断言被拒绝从而锁死新行为的版本边界。测试规范与仓库实测根据.claude/docs/testing-guidelines.mdAPI 测试使用Testcontainers Spock组合位于functional-test/目录。仓库中已有大量此类真实测试例如 ConfigSpec.groovy它通过APITest注解标记、继承BaseContainer获取测试容器客户端并直接以doPost(/projects, testProperties)的方式调用 API。测试断言同样覆盖错误条件与边界场景例如对项目配置键的 JSON 读写验证ConfigSpec.groovy。备注functional-test/src/test/groovy/org/rundeck/tests/functional/api/job/JobServerUrlSpec.groovy等测试中还直接出现/api/50/projects这类硬编码版本路径说明测试代码与版本常量同样需要随版本演进同步维护。Phase 4DTO 与Schema注解DTO数据传输对象是请求与响应数据结构的载体必须使用独立的数据类而非内联 Schema 定义。这样做的好处包括编译期类型安全、OpenAPI 规范直接从代码结构自动生成、DTO 变更自动同步到规范避免规范与代码漂移。DTO 编写模板Schema(description Project response) class ProjectResponse { Schema(description Project name, example MyProject) String name Schema(description Project description) String description Schema(description Creation date, example 2025-01-01T00:00:00Z) String created }字段级Schema应尽量提供description与example。根据 api-guidelines.md 的补充建议请求 DTO 还应标记required true并配合CompileStatic使用CompileStatic Schema(description Request to create a new user) class CreateUserRequest { Schema(description Username, required true, example johndoe) String username Schema(description Password, required true) String password Schema(description User roles, required true) ListString roles }在注解中引用 DTO规范强烈推荐用Schema(implementation ClassName)引用 DTO而不是手写type objectrequiredProperties的内联对象定义ApiResponse( responseCode 201, description User created successfully, content Content( mediaType MediaType.APPLICATION_JSON, schema Schema(implementation UserCreatedResponse) ) )配合控制器方法的Body参数可以实现类型安全的请求绑定def apiCreate(Body CreateUserRequest request) { // Access properties with type safety: request.username, request.password }Phase 5控制器与端点注解核心实操控制器是端点实现的载体注解分三个层级类级Controller、方法级Operation/Tag/Response、参数级Parameters/Body。Step 1类级Controller注解必填。没有Controller方法上的所有注解都不会出现在生成的 OpenAPI 规范中。Controller(value /api/44) class ProjectController { // ... }value参数可以指定整个控制器所有端点的统一基路径例如/api/44/projects方法注解里的uri再写相对路径。Step 2方法级注解只读端点GETOperation( method GET, summary List Projects, description Returns a list of all projects accessible to the user ) Tag(name Project) ApiResponse( responseCode 200, description Project list successfully retrieved, content Content( mediaType application/json, schema Schema(implementation ProjectListResponse.class) ) ) Get(uri /projects, produces MediaType.APPLICATION_JSON) def listProjects() { // implementation }带请求体POST/PUT通过Operation.requestBody描述请求体同时配合Post/PutOperation( method POST, summary Create Project, description Creates a new project with the specified configuration, requestBody RequestBody( description Project configuration, content Content( mediaType application/json, schema Schema(implementation ProjectCreateRequest.class) ), required true ) ) ApiResponse( responseCode 201, description Project created successfully, content Content( mediaType application/json, schema Schema(implementation ProjectResponse.class) ) ) Post(uri /projects) def createProject() { // implementation }查询/路径参数使用Parameters([...])数组路径参数用ParameterIn.PATH查询参数用ParameterIn.QUERYParameters([ Parameter( name project, in ParameterIn.PATH, description Project name, required true, schema Schema(type string) ), Parameter( name includeArchived, in ParameterIn.QUERY, description Include archived items, schema Schema(type boolean, defaultValue false) ) ]) Get(uri /project/{project}/jobs) def getProjectJobs() { // implementation }关于Operation.description的写作要求不要写Get data或Update resource这类通用描述。规范的描述应当说明端点的业务目的期望的输入/输出行为在整体工作流中的集成上下文副作用或重要注意事项授权要求与 API 版本信息例如 Authorization required:createforjobresource type — Since: v46。关于Tag的规范Tag 是 OpenAPI 文档的归类维度Rundeck 有严格的约定大小写规范使用规范定义的标准 Tag禁止小写用Jobs而非jobs每端点只能一个 Tag要么Tag(name Project)要么在Operation中写tags [Project]禁止tags [Project, Configuration]这种多 Tag 写法标准 Tag 参考表来自 api-guidelines.mdTag用途ACL访问控制列表操作Calendars日历管理操作Configuration配置管理操作Health健康检查操作Jobs任务管理操作System系统操作User用户管理操作WebhookWebhook 操作Phase 6build.gradle 依赖与 OpenAPI 目标文件新端点所在的模块需要声明 Micronaut OpenAPI 与 Swagger 注解依赖。版本号统一由gradle.properties中的属性集中管理compileOnly io.micronaut.openapi:micronaut-openapi:${micronautOpenapiVersion} implementation io.swagger.core.v3:swagger-annotations:${swaggerVersion}根据 api-guidelines.md完整依赖清单还包含implementation io.micronaut:micronaut-http-server:${micronautVersion} implementation io.micronaut:micronaut-inject:${micronautVersion} implementation io.micronaut:micronaut-inject-java:${micronautVersion} implementation io.micronaut:micronaut-inject-groovy:${micronautVersion} implementation io.micronaut:micronaut-core:${micronautVersion}新插件声明独立的目标文件OpenAPI 规范由compileGroovy任务触发 Micronaut 注解处理器生成。每个插件必须声明唯一的 target filerundeckapp再通过 additional files 机制合并各插件的规范。目标文件配置模板tasks.withType(GroovyCompile) { def target new File( project.rootDir, rundeckapp/build/openapi/${project.name}.yml ).absolutePath configure(groovyOptions) { forkOptions.jvmArgs [ -Xmx1024m, -Dmicronaut.openapi.target.file${target}.toString() ] } }源码佐证rundeckapp 的规范后处理在 rundeckapp/build.gradle 中有一个专门的fixOpenApiSpec任务L590-L631它读取编译产物build/classes/groovy/main/META-INF/swagger/rundeck-api.yml并从ApiVersions.groovy中正则提取API_CURRENT_VERSION_STR的值把规范中$API_VERSION$占位符替换为真实版本号。这印证了两点OpenAPI 规范的最终产物路径是rundeckapp/build/classes/groovy/main/META-INF/swagger/rundeck-api.yml版本号字符串的单一事实来源就是ApiVersions.groovy中的API_CURRENT_VERSION_STR改动它会影响规范生成结果。Phase 7运行测试与验证Skill 文档给出的验证命令如下# API 测试 ./gradlew :functional-test:apiTest # 验证 OpenAPI 规范已生成 ls rundeckapp/build/classes/groovy/main/META-INF/swagger/rundeck-*.yml # 全量测试套件 ./gradlew test注意验证清单中的关键检查点构建后确认 YAML 生成于rundeckapp/build/classes/groovy/main/META-INF/swagger/目录确认 OpenAPI 规范包含新增端点确认旧版本 API 测试仍通过、新版本测试通过。Phase 8更新官方文档任何 API 变更都必须同步文档Skill 明确列出三项更新 Rundeck 官方 API 参考文档更新 API 版本历史Version History记录变更如果是新 API 版本说明新增/改动了什么内容。注解速查表类级注解说明Controller(value /api/44/base-path)必填。Micronaut 控制器可指定基路径缺失时方法不会出现在规范中方法级注解说明Get / Post / Put / Delete(uri /path)必填。HTTP 方法绑定Operation(...)必填。OpenAPI 操作定义summary / description / requestBodyTag(name Category)必填。分组归类或Operation(tags [Category])仅限一个ApiResponse(...)必填。响应定义responseCode / description / contentParameters([...])可选。查询/路径参数声明数据类型注解说明Schema(...)必填。用于 DTO 类与字段定义数据结构交付 Checklist设计阶段API 设计已评审HTTP 方法、路径、版本化新功能已提升 API 版本build.gradle已添加 Micronaut/Swagger 依赖新插件已配置 OpenAPI 目标文件控制器已用Controller注解每个方法都有Get/Post/Put/Delete每个方法都有带详细描述的Operation每个方法恰好一个 TagTag(name X)或Operation中tags [X]每个方法都有ApiResponsePOST/PUT 已声明请求体需要时已声明参数数据类型DTO 类已注解SchemaDTO 字段已注解Schema测试API 测试先行TDD测试验证新 API 版本可用测试验证旧 API 版本不支持新行为API 测试全部通过验证构建并验证rundeckapp/build/classes/groovy/main/META-INF/swagger/下 YAML 已生成OpenAPI 规范包含新增端点Rundeck 官方文档已更新常见错误与纠正❌ 禁止忘记Controller注解方法不会出现在规范中新功能却使用旧 API 版本跳过 API 版本测试DTO 遗漏Schema忘记更新 Rundeck 官方文档。✅ 必须始终使用Controller新行为必须提升 API 版本新旧两个 API 版本都要测试完整注解所有 DTO更新官方文档。延伸阅读.claude/skills/create-api-endpoint/SKILL.md— 本文的原始 Skill 定义.claude/docs/api-guidelines.md— 完整注解指南与标准 Tag 表.claude/docs/testing-guidelines.md— 测试哲学与 API 测试要求ApiVersions.groovy — API 版本常量与当前版本配置的单一事实来源ApiController.groovy — 版本条件分支的真实使用示例rundeckapp/build.gradle —fixOpenApiSpec任务与规范生成后处理逻辑ConfigSpec.groovy — Testcontainers Spock 的功能性 API 测试实例。结合上述源码可以确认Rundeck 的 API 端点开发是一套版本常量集中管理、行为按版本条件隔离、测试正反双向验证、注解驱动规范生成的完整体系。遵循create-api-endpointSkill 的八阶段流程就能以可预期、可验证、可回溯的方式为 Rundeck 贡献新的 REST API 端点。赞分享运维任务调度后端【免费下载链接】rundeckEnable Self-Service Operations: Give specific users access to your existing tools, services, and scripts项目地址https://gitcode.com/gh_mirrors/ru/rundeck点击查看免费下载相关推荐Rundeck API 开发规范基于 Grails Controller 与 Micronaut OpenAPI 注解的规格生成实战指南Rundeck API 开发规范基于 Grails Controller 与 Micronaut OpenAPI 注解的规格生成实战指南 本文是 Rundec运维任务调度后端OptiScaler 超采样替换 3 步上手免费启用帧生成与画质调校OptiScaler 超采样替换 3 步上手免费启用帧生成与画质调校 OptiScaler 是一个开源的超采样替换与帧生成工具它以 DLL 注入的方式把你图形学游戏开发Rundeck 后端测试实战指南基于 create-test 技能编写 Spock 单元测试与 Testcontainers API/功能测试Rundeck 后端测试实战指南基于 create test 技能编写 Spock 单元测试与 Testcontainers API/功能测试 本篇技术指南围运维任务调度后端上一篇显卡驱动卸载不干净怎么办DDU 免费开源工具彻底清理驱动的完整手册下一篇深入 mamba::solverMamba 包求解器通用接口与 LibSolv 实现全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考