Openapi swagger

Skill a5c-ai/babysitter/library/specializations/technical-documentation/skills/openapi-swagger

Babysitter enforces obedience on agentic workforces and enables them to manage extremely complex tasks and workflows through deterministic, hallucination-free self-orchestration

Install

npx -y skills add a5c-ai/babysitter --skill openapi-swagger

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

8.2 KB, as published. Nobody here has run it

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

Parse specification - Load and parse OpenAPI/Swagger file
Validate syntax - Check for schema compliance
Lint for best practices - Apply Spectral rules
Generate documentation - Create ReDoc/Swagger UI output
Generate samples - Create code examples
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