Agent skill · software engineering · sickn33
openapi-spec-generator
Generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs.
Why this skill is useful
Generates complete OpenAPI specifications from natural language or code, which is a niche capability not commonly known by AI.
What it needs
About 6k tokens when loaded. Last updated 2026-08-07. 44,571 stars on the source repository.
What this skill does
OpenAPI / Swagger Specification Generator When to Use Use this skill when you need generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs. Use this skill whenever the user mentions OpenAPI, Swagger, API spec, REST API documentation, YAML/JSON API schema, endpoint documentation, API... Generate complete, valid OpenAPI 3.x or Swagger 2.0 specifications from descriptions, code, or partial specs. Workflow Step 1 — Gather Context Before writing any YAML/JSON, ask (or infer from context) the following: Question Why it matters --- --- OpenAPI 3.x or Swagger 2.0? Different info, servers/host, components/definitions structure Output format: YAML or JSON? YAML default unless user specifies JSON What does this API do? Sets info.title, info.description, tags List of endpoints (or code to extract from)? Core paths object Authentication type(s)? securitySchemes — see reference Common data models or entities? components/schemas / definitions Any existing partial spec to extend? Merge rather than overwrite If the user provides code (Express routes, FastAPI, Django URLs, Spring controllers, etc.), extract endpoints automatically — do not ask what the user already told you. Step 2 — Build the Spec Follow the structure guide for the chosen version. Always produce a complete, valid spec — never leave placeholder comments like # TODO: add schema. OpenAPI 3.x Skeleton Swagger 2.0 Skeleton Step 3 — Schemas and Models Always use $ref for any schema used in more than one place. Include example or examples on every schema and response body. Mark required fields with the required array. Use nullable: true (OAS 3.0) or x-nullable: true (Swagger 2.0) for optional nullable fields. Prefer format keywords: int32, int64, float, date, date-time, uuid, email, uri, byte, binary. Common schema patterns: Step 4 — Security Schemes Read reference/security-schemes.md for detailed patterns. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills sickn33/openapi-spec-generator