openapi-spec-generator – Coding skill for AI agents

OpenAPI / Swagger Specification Generator

When to Use

Use when extracting or drafting OpenAPI/Swagger descriptions from actual routes, models, requirements or an existing specification. State unconfirmed behavior separately rather than inventing a complete production contract.

Generate complete, valid OpenAPI 3.x or Swagger 2.0 specifications from descriptions, code, or partial specs.

Version and completeness boundaries

This tree does not bundle the named reference/security-schemes.md or common-patterns.md files. Use available inline guidance and current version-specific specification, not fabricated reference contents. Skeletons below are incomplete until every reference/security scheme is defined; never label them validated as-is. OpenAPI 3.1 nullability uses JSON Schema types/unions rather than 3.0 nullable. Do not invent status codes, auth, examples or required fields just to fill the checklist; distinguish observed contract from proposed design. Limit/disable remote reference fetching when validating untrusted specs. See [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0.html).

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

openapi: "3.1.0"
info:
  title: <API Title>
  version: "1.0.0"
  description: <Short description>
  contact:
    name: <Team or Author>
    email: <[email protected]>
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
tags:
  - name: <Tag>
    description: <Tag description>
paths:
  /resource:
    get:
      summary: List resources
      operationId: listResources
      tags: [<Tag>]
      parameters: []
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceList"
              example:
                items: []
                total: 0
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      security:
        - BearerAuth: []
components:
  schemas: {}
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  securitySchemes: {}

Swagger 2.0 Skeleton

swagger: "2.0"
info:
  title: <API Title>
  version: "1.0.0"
  description: <Short description>
host: api.example.com
basePath: /v1
schemes: [https]
consumes: [application/json]
produces: [application/json]
tags: []
paths: {}
definitions: {}
securityDefinitions: {}

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:

# Pagination wrapper
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

# Standard error
Error:
  type: object
  required: [code, message]
  properties:
    code:
      type: string
      example: RESOURCE_NOT_FOUND
    message:
      type: string
      example: The requested resource was not found.
    details:
      type: object
      additionalProperties: true

# Timestamps mixin (use allOf)
Timestamps:
  type: object
  properties:
    createdAt:
      type: string
      format: date-time
    updatedAt:
      type: string
      format: date-time

Step 4 — Security Schemes

Read reference/security-schemes.md for detailed patterns. Quick reference:

| Scheme | OAS 3.x type | Notes |

|---|---|---|

| Bearer JWT | http, scheme bearer | Most common for REST APIs |

| API Key (header) | apiKey, in header | e.g. X-API-Key |

| API Key (query) | apiKey, in query | Avoid — leaks in logs |

| OAuth 2 | oauth2 | Use flows to define grant types |

| Basic Auth | http, scheme basic | Only over HTTPS |

| OpenID Connect | openIdConnect | Provide openIdConnectUrl |

Apply security globally at the root and override per-operation only where it differs (e.g., public endpoints use security: []).

Step 5 — Parameters

Path parameters — always required: true:

parameters:
  - name: userId
    in: path
    required: true
    schema:
      type: string
      format: uuid
    example: 123e4567-e89b-12d3-a456-426614174000

Query parameters — document defaults and enums:

  - name: status
    in: query
    schema:
      type: string
      enum: [active, inactive, pending]
      default: active

Headers — include X-Request-ID, correlation IDs, etc. as common parameters defined under components/parameters.

Step 6 — Response Codes

Always include at minimum:

| Code | When |

|---|---|

| 200 | Successful GET, PUT, PATCH |

| 201 | Successful POST that creates a resource |

| 204 | Successful DELETE (no body) |

| 400 | Validation / bad request |

| 401 | Missing or invalid auth |

| 403 | Authenticated but not authorized |

| 404 | Resource not found |

| 409 | Conflict (duplicate, state mismatch) |

| 422 | Unprocessable entity (semantic errors) |

| 429 | Rate limited |

| 500 | Internal server error |

Use $ref to components/responses for 401, 403, 404, 429, 500 to avoid repetition.

Step 7 — Quality Checklist

Before delivering the spec, verify:

• [ ] openapi or swagger version field present
• [ ] Every path has at least one operation
• [ ] Every operation has operationId (camelCase, unique)
• [ ] Every operation has at least one 200/201/204 response
• [ ] 4xx and 5xx responses defined for all operations
• [ ] All $ref targets exist in components/ or definitions/
• [ ] Required fields listed in required array for all request/response bodies
• [ ] Security schemes defined AND applied
• [ ] At least one example per schema or response body
• [ ] Tags defined at root level to match operation tags
• [ ] No orphaned schemas (everything in components/schemas is referenced)

Step 8 — Output

1. Emit the complete YAML (or JSON) spec in a code block labeled yaml or json.

2. After the spec, provide a brief summary table of endpoints generated.

3. Offer to:

• Export as .yaml / .json file
• Validate against Spectral or swagger-parser
• Generate mock server config (Prism)
• Generate client SDK stubs (language of choice)

---

Extracting from Code

When the user provides source code, extract:

Express / Koa / Fastify (Node.js)

• Look for .get(), .post(), .put(), .patch(), .delete() calls
• Route params :param → path parameter {param}
• Middleware like authenticate → note security requirement
• req.body, req.query, req.params usage → infer request schema

FastAPI / Flask (Python)

• Decorators: @app.get(), @router.post(), etc.
• Pydantic models → translate directly to JSON Schema
• Query(), Path(), Body() → map to parameter location

Spring Boot (Java)

• @GetMapping, @PostMapping, etc.
• @PathVariable, @RequestParam, @RequestBody
• DTO classes → schemas

Django REST Framework

• ViewSet and Router → CRUD endpoints
• Serializer fields → schema properties

Rails

… (full content is in the download package)