http-api-openapi

matt-riley 的头像作者 matt-riley

保持HTTP处理器和OpenAPI(openapi.yaml)同步。在添加/更改端点、请求/响应模式、认证要求或错误形状时使用。

📖 中文导读:保持HTTP处理器和OpenAPI(openapi.yaml)同步。在添加/更改端点、请求/响应模式、认证要求或错误形状时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: http-api-openapi description: Keep HTTP handlers and OpenAPI (openapi.yaml) in sync. Use when adding/changing endpoints, request/response schemas, auth requirements, or error shapes. license: MIT compatibility: Requires bash, git, Go; optional Node/npm + swagger-cli for validation. metadata: repo: mjrwtf runner: github-copilot-cli version: 1.2 allowed-tools: Bash(git:) Bash(make:) Bash(go:) Bash(npm:) Bash(swagger-cli:*) Read

Tooling assumptions

  • Use a terminal runner with bash and git available.
  • Prefer make targets when available; fall back to direct CLI commands when needed.

Source of truth

  • OpenAPI spec: openapi.yaml at the repo root.

Typical workflow

  1. Update openapi.yaml (paths, schemas, auth).
  2. Validate the spec:
make validate-openapi

If swagger-cli isn’t installed:

npm install -g @apidevtools/swagger-cli
  1. Implement the handler changes in Go (and keep auth consistent with the spec).
  2. Run tests:
make test

Project-specific notes

  • Authenticated endpoints use Bearer token auth (see README’s Auth section).
  • Be explicit about error responses and status codes in the spec when behavior changes.