Generate OpenAPI/Swagger specs from test automation code

This skill generates complete, valid OpenAPI 3.x or Swagger 2.0 specifications from natural-language descriptions, source code, or partial specs - never leaving placeholder comments like # TODO: add schema. It follows an eight-step workflow: gather context (spec version, YAML vs JSON output, what the API does, endpoint list or code to extract from, auth types, common data models, and any existing partial spec to merge rather than overwrite); build the spec from a version-specific skeleton (OpenAPI 3.x with info/servers/paths/components, or Swagger 2.0 with host/basePath/definitions); define schemas and models using $ref for anything reused, an example on every schema/response, required arrays, nullable/x-nullable for optional fields, and standard format keywords (int32, uuid, date-time, etc.), with named common patterns for a pagination wrapper, a standard error object, and a timestamps mixin via allOf; configure security schemes (Bearer JWT, header API key, OAuth2, Basic Auth, OpenID Connect) applied globally with per-operation overrides for public endpoints; document path and query parameters (path parameters always required: true, query parameters with documented defaults and enums, common headers like X-Request-ID under components/parameters); and define response codes, always including at minimum 200/201/204 success codes plus 400/401/403/404/409/422/429/500 error codes, referencing shared components/responses for the repeated error codes. A quality checklist gates delivery: version field present, every path has an operation, every operation has a unique camelCase operationId and at least one success response plus 4xx/5xx responses, all $ref targets resolve, required fields are listed, security schemes are both defined and applied, every schema/response has an example, tags match between root and operations, and no schema is orphaned. Output is the complete spec in a labeled code block plus a summary table of generated endpoints, with an offer to export to a file, validate against Spectral or swagger-parser, generate a Prism mock server config, or generate client SDK stubs. When source code is provided, it extracts endpoints automatically rather than re-asking what was already given: Express/Koa/Fastify route methods and :param path params, FastAPI/Flask decorators and Pydantic models (translated directly to JSON Schema), Spring Boot mapping annotations and DTO classes, Django REST Framework ViewSets/Routers/Serializers, and Rails routes.rb resources and strong params. After delivering a spec, it offers to hand off to a separate API Test Case Generator skill if installed, using the generated spec as input.

Use it whenever OpenAPI, Swagger, an API spec, REST API documentation, or a YAML/JSON API schema is mentioned - generating a spec from scratch, from existing code, or extending a partial spec. When code is provided, extract endpoints directly from it rather than asking the user to restate what the code already shows. Do NOT deliver a spec with placeholder TODOs or skip the quality checklist - an incomplete or unvalidated spec defeats the purpose of a "production-ready" generator.

Inputs: a natural-language API description, source code (Express/FastAPI/Django/Spring/Rails, etc.), or a partial existing spec, plus the target version (OpenAPI 3.x or Swagger 2.0) and output format (YAML or JSON). Outputs: a complete, checklist-verified spec with populated schemas, security schemes, parameters, and response codes, a summary table of generated endpoints, and optional next steps (file export, Spectral/swagger-parser validation, Prism mock config, client SDK stubs).

PagedResult:
  type: object
  required: [items, total, page, pageSize]
  properties:
    items:
      type: array
      items:
        $ref: "#/components/schemas/Resource"
    total:
      type: integer
      format: int64
      example: 100
    page:
      type: integer
      format: int32
      example: 1
    pageSize:
      type: integer
      format: int32
      example: 20

Produces specs compatible with Spectral and swagger-parser for validation, Prism for mock server generation, and client SDK generators of the user's chosen language, and hands off to a companion API Test Case Generator skill when installed. For complex auth or pagination setups it draws on two bundled reference files: reference/security-schemes.md for detailed examples of each auth type, and reference/common-patterns.md for pagination, HATEOAS, problem+json, webhooks, and file-upload patterns not covered in the base workflow.

Backend developers and API designers who need a complete, validated OpenAPI or Swagger specification generated from a description or existing code rather than hand-written from scratch.