a5c-ai/openapi-swagger

OpenAPI/Swagger Skill

Expert skill for OpenAPI/Swagger specification analysis and documentation generation.

Capabilities

• Parse and validate OpenAPI 3.x and Swagger 2.0 specifications
• Generate API documentation from specs (ReDoc, Swagger UI)
• Detect breaking changes between API versions
• Validate request/response examples against schemas
• Generate code samples in multiple languages
• Lint OpenAPI specs for best practices (Spectral rules)
• Convert between OpenAPI formats (YAML/JSON, version migration)

Usage

Invoke this skill when you need to:

• Validate and lint OpenAPI specifications
• Generate API reference documentation
• Detect breaking changes between API versions
• Create code samples from API specs
• Migrate between OpenAPI versions

Inputs

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | specPath | string | Yes | Path to OpenAPI/Swagger spec file | | action | string | Yes | validate, lint, generate-docs, diff, generate-samples | | outputDir | string | No | Output directory for generated content | | targetVersion | string | No | Target OpenAPI version for migration | | languages | array | No | Languages for code sample generation | | rulesets | array | No | Spectral ruleset files to apply |

Input Example

{
  "specPath": "./api/openapi.yaml",
  "action": "lint",
  "rulesets": [".spectral.yaml"],
  "outputDir": "docs/api"
}

Output Structure

Validation Output

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "path": "paths./users.get.responses.200",
      "message": "Response should have a description",
      "severity": "warning"
    }
  ],
  "info": {
    "title": "My API",
    "version": "1.0.0",
    "openApiVersion": "3.1.0"
  }
}

Breaking Changes Output

{
  "breaking": [
    {
      "type": "removed-endpoint",
      "path": "DELETE /users/{id}",
      "description": "Endpoint removed in new version"
    },
    {
      "type": "changed-type",
      "path": "POST /users.requestBody.email",
      "from": "string",
      "to": "object"
    }
  ],
  "nonBreaking": [
    {
      "type": "added-endpoint",
      "path": "GET /users/{id}/profile"
    }
  ]
}

OpenAPI Specification Patterns

OpenAPI 3.1 Template

openapi: 3.1.0
info:
  title: My API
  description: API description with **Markdown** support
  version: 1.0.0
  contact:
    name: API Support
    email: [email protected]
  license:
    name: MIT
    identifier: MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

tags:
  - name: users
    description: User management operations

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      description: Returns a paginated list of users
      tags:
        - users
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
              examples:
                success:
                  $ref: '#/components/examples/UserListExample'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier
        email:
          type: string
          format: email
          description: User email address
        name:
          type: string
          description: Display name
        createdAt:
          type: string
          format: date-time

    UserList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'

  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1

    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

Spectral Configuration

.spectral.yaml

extends:
  - spectral:oas

rules:
  # Require descriptions
  operation-description: warn
  operation-operationId: error

  # Naming conventions
  operation-operationId-valid-in-url: true
  path-params: error

  # Security
  operation-security-defined: error

  # Custom rules
  path-must-have-tag:
    description: Every path must have at least one tag
    given: $.paths[*][*]
    severity: warn
    then:
      field: tags
      function: length
      functionOptions:
        min: 1

  require-example:
    description: Responses should have examples
    given: $.paths[*][*].responses[*].content[*]
    severity: info
    then:
      field: examples
      function: truthy

Code Sample Generation

Generated Samples

// JavaScript (fetch)
const response = await fetch('https://api.example.com/v1/users', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

# Python (requests)
import requests

response = requests.get(
    'https://api.example.com/v1/users',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    }
)
data = response.json()

# cURL
curl -X GET 'https://api.example.com/v1/users' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

Workflow

1. Parse specification - Load and parse OpenAPI/Swagger file
2. Validate syntax - Check for schema compliance
3. Lint for best practices - Apply Spectral rules
4. Generate documentation - Create ReDoc/Swagger UI output
5. Generate samples - Create code examples
6. Report findings - Output validation results

Dependencies

{
  "devDependencies": {
    "@stoplight/spectral-cli": "^6.11.0",
    "swagger-cli": "^4.0.0",
    "@redocly/cli": "^1.0.0",
    "openapi-generator-cli": "^2.7.0",
    "oasdiff": "^1.0.0"
  }
}

CLI Commands

# Validate spec
npx @redocly/cli lint openapi.yaml

# Spectral linting
npx spectral lint openapi.yaml

# Generate ReDoc documentation
npx @redocly/cli build-docs openapi.yaml -o docs/index.html

# Detect breaking changes
oasdiff breaking old-api.yaml new-api.yaml

# Generate code samples
npx openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./sdk

Best Practices Applied

• Use $ref for reusable components
• Include examples for all schemas
• Document all error responses
• Use semantic versioning
• Include operationId for all operations
• Tag all endpoints
• Provide server URLs for all environments

References

• OpenAPI Specification: https://spec.openapis.org/oas/latest.html
• Spectral: https://stoplight.io/open-source/spectral
• ReDoc: https://redocly.com/redoc
• Swagger UI: https://swagger.io/tools/swagger-ui/
• OpenAPI Generator: https://openapi-generator.tech/

Target Processes

• api-doc-generation.js
• api-reference-docs.js
• sdk-doc-generation.js
• docs-testing.js