sickn33/agentic-awesome-skills/openapi-spec-generator

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.

Workflow

Step 1 — Gather Context

Before writing any YAML/JSON, ask (or infer from context) the following:

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: <contact@example.com>
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:

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:

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

• routes.rb resource routes → standard REST endpoints
• Strong params → request body schema

Reference Files

• reference/security-schemes.md — Detailed security scheme examples for all auth types
• reference/common-patterns.md — Pagination, HATEOAS, problem+json, webhooks, file upload patterns

Read these when the user asks about a specific pattern or when generating complex auth/pagination setups.

After Completing the OpenAPI/Swagger Specification design

Once the OpenAPI/Swagger Specification output is delivered, ask the user:

"Would you like me to generate API test cases for this design? (yes/no)"

If the user says yes:

• Check if the API Test Case Generator skill is available in the installed skills list
• If the skill is available:
• Read and follow the instructions in the API Test Case Generator skill
• Use the specification output above as the input
• If the skill is NOT available:
• Inform the user: "It looks like the API Documentation skill isn't installed.

You can install it and re-run.

If the user says no:

• End the task here

Limitations

• Use this skill only when the task clearly matches its upstream source and local project context.
• Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
• Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.