openapi-swagger

name	openapi-swagger
description	Expert skill for OpenAPI/Swagger specification analysis, validation, and documentation generation. Parse and validate specs, detect breaking changes, generate code samples, and lint for best practices.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep
backlog-id	SK-001
metadata	{"author":"babysitter-sdk","version":"1.0.0"}
graph	{"domains":["domain:software-engineering"],"specializations":["specialization:technical-documentation"],"skillAreas":["skill-area:api-doc-generation","skill-area:reference-docs"],"roles":["role:technical-writer","role:documentation-engineer"]}

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: [e-mail]
  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     
      
         
      
          
          
      
        
            
          
            
              
                 
              
                
                   
        
           


  
    
       
      
         
         
      
        
           
           
            
        
           
           
             
        
           
            
        
           
           

    
       
      
        
           
          
             
        
           

  
    
       
       
      
         
         
         

    
       
       
      
         
         
         
         

  
    
        
      
        
          
             

  
    
       
       
       


    []

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: 

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