Skip to content

skillBackend and APIs

OpenAPI Spec Authoring

Writes or repairs an OpenAPI 3.1 spec that matches the real code, lints it, and checks that a generated client compiles against it.

npx workspacetemplates add openapi-spec-authoring --tool claude-code

Writes 1 file to .claude/skills/openapi-spec-authoring/

.claude/skills/openapi-spec-authoring/SKILL.md29 lines · 1.7 KBFile
---
name: openapi-spec-authoring
description: Writes or repairs an OpenAPI 3.1 spec that matches the real code, lints it, and checks that a generated client compiles against it.
---

# OpenAPI spec authoring

The code is the truth; the spec must prove it.

## Steps

1. List every route with method, path, auth and the request and response types in the code. Look at actual serializers and validators, not only type names.
2. Write OpenAPI 3.1 (JSON Schema compatible). Put every reusable object under `components/schemas` and reference it with `$ref`; never paste the same shape twice.
3. Give every operation a unique `operationId` in verb-noun form (`listOrders`, `createOrder`). Generators use it as the method name.
4. Describe every response that can occur, not only 200: 400, 401, 403, 404, 409, 422, 429 and the 5xx shape, all pointing to one shared error schema.
5. Be exact about types: `format: date-time`, integer ranges, string `maxLength` and `pattern`, enums, `required` lists. Use nullable via `type: [string, "null"]` in 3.1. Mark `additionalProperties` deliberately.
6. Declare `securitySchemes` and apply them per operation; leave public routes with an empty security list.
7. Add one realistic `example` per request and response.
8. Lint with Spectral (`npx @stoplight/spectral-cli lint openapi.yaml`) and fix errors. Generate a client with your chosen generator and compile it.
9. Add a contract test that validates real responses from the test suite against the schemas.

## Rules

- Never describe behavior the code does not have.
- Never leave `type: object` with no properties unless it is truly free-form.

## Report

Routes covered and missing, lint results, generated client status and contract test added.

What it does

A spec that drifts from the code is worse than none, because clients trust it. This skill has the agent derive the spec from the actual routes and responses, reuse shared components and describe errors, rather than guessing from the route names.

It finishes by linting the document and generating a client, since a spec that lints but cannot generate code usually has a modelling problem hiding in it.

Example

you › We have no OpenAPI spec for the orders service. Write one.

agent › Wrote openapi.yaml (OpenAPI 3.1): 14 operations, 9 shared schemas, one Problem error schema used by all error responses. Spectral reports 0 errors, 2 warnings (missing example on two PATCH bodies, added). Generated a TypeScript client and compiled it. Added a test that validates responses from the test suite against the schemas; it found that GET /orders/{id} omits cancelledAt, now optional in the spec.

Questions

Should the spec be generated from code or written by hand?
Either works. If your framework generates it, the skill checks and tightens the output; if not, it writes the file and adds a test so it cannot drift.
Does it support Swagger 2?
It can read one, but it writes 3.1 and notes what changed when migrating.
  • API Error Responses

    SkillBackend and APIs

    Free
  • API Pagination Design

    SkillBackend and APIs

    Free
  • API Versioning Strategy

    SkillBackend and APIs

    Free
  • Background Job Design

    SkillBackend and APIs

    Free