About

Imported from personamanagmentlayer/pcl (stdlib/api/openapi-expert/SKILL.md). Install upstream with npx skills add personamanagmentlayer/pcl --skill openapi-expert. Copyright stays with the author.

OpenAPI Expert

Name: openapi-expert
Author: personamanagmentlayer

Expert guidance for OpenAPI Specification (formerly Swagger) - industry-standard for describing RESTful APIs with automatic documentation and code generation.

Core Concepts

OpenAPI Specification (OAS)

API description format (YAML/JSON)
Version 3.1 (latest) and 3.0
Machine-readable API contracts
Automatic documentation generation
Client/server code generation
API validation and testing

Key Components

Paths (endpoints)
Operations (HTTP methods)
Parameters
Request/Response bodies
Schemas (data models)
Security schemes
Components (reusable objects)

Advanced Features

Webhooks (OpenAPI 3.1)

webhooks:
  postCreated:
    post:
      summary: Post created webhook
      operationId: onPostCreated
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Post'
      responses:
        '200':
          description: Webhook received

Polymorphism (oneOf/anyOf/allOf)

components:
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
      discriminator:
        propertyName: petType
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'

    Cat:
      allOf:
        - $ref: '#/components/schemas/PetBase'
        - type: object
          properties:
            petType:
              type: string
              enum: [cat]
            meow:
              type: string

    Dog:
      allOf:
        - $ref: '#/components/schemas/PetBase'
        - type: object
          properties:
            petType:
              type: string
              enum: [dog]
            bark:
              type: string

Code Generation

# Install OpenAPI Generator
npm install -g @openapitools/openapi-generator-cli

# Generate TypeScript client
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client

# Generate Python Flask server
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python-flask \
  -o ./server

# Generate Java Spring server
openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server

Validation

# Install Spectral (OpenAPI linter)
npm install -g @stoplight/spectral-cli

# Validate spec
spectral lint openapi.yaml

# Custom ruleset
# .spectral.yaml
extends: spectral:oas
rules:
  operation-tags: error
  operation-operationId: error
  no-$ref-siblings: error

Documentation Generation

# Swagger UI
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/openapi.yaml \
  -v $(pwd):/usr/share/nginx/html \
  swaggerapi/swagger-ui

# Redoc
docker run -p 8080:80 \
  -e SPEC_URL=openapi.yaml \
  -v $(pwd):/usr/share/nginx/html \
  redocly/redoc

Best Practices

Use semantic versioning
Include examples in schemas
Provide clear descriptions
Use components for reusability
Define proper error responses
Include security schemes
Add operation IDs
Tag operations logically
Validate specifications
Version your APIs

Reference Documentation

Detailed material lives alongside this skill and is read on demand:

Basic OpenAPI Specification

Resources

OpenAPI Spec: https://spec.openapis.org/
Swagger Editor: https://editor.swagger.io/
OpenAPI Tools: https://openapi.tools/
Stoplight Studio: https://stoplight.io/studio

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/personamanagmentlayer-pcl-openapi-expert/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

personamanagmentlayer-pcl-openapi-expert.ocm.jsonjson

{
  "ocm": "1",
  "id": "personamanagmentlayer-pcl-openapi-expert",
  "kind": "skill",
  "name": "openapi-expert",
  "description": "Expert-level OpenAPI/Swagger specification for API design, documentation, and code generation. Use when the user mentions swagger, API specs, REST, API design, or documentation, or when the task involves OpenAPI Specification, Webhooks, or Polymorphism.",
  "publisher": "personamanagmentlayer",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "openapi",
      "swagger",
      "api-spec",
      "rest",
      "api-design",
      "documentation",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Expert-level OpenAPI/Swagger specification for API design, documentation, and code generation. Use when the user mentions swagger, API specs, REST, API design, or documentation, or when the task involves OpenAPI Specification, Webhooks, or Polymorphism."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/personamanagmentlayer/pcl",
      "path": "stdlib/api/openapi-expert/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/personamanagmentlayer/pcl/blob/HEAD/stdlib/api/openapi-expert/SKILL.md",
      "key": "personamanagmentlayer/pcl/stdlib/api/openapi-expert/SKILL.md"
    },
    "allowed_tools": [
      "Read",
      "Write",
      "Edit",
      "Bash(openapi:*, swagger:*)"
    ]
  },
  "instructions": "# OpenAPI Expert\n\nExpert guidance for OpenAPI Specification (formerly Swagger) - industry-standard for describing RESTful APIs with automatic documentation and code generation.\n\n## Core Concepts\n\n### OpenAPI Specification (OAS)\n\n- API description format (YAML/JSON)\n- Version 3.1 (latest) and 3.0\n- Machine-readable API contracts\n- Automatic documentation generation\n- Client/server code generation\n- API validation and testing\n\n### Key Components\n\n- Paths (endpoints)\n- Operations (HTTP methods)\n- Parameters\n- Request/Response bodies\n- Schemas (data models)\n- Security schemes\n- Components (reusabl",
  "cost": {
    "context_tokens": 870
  }
}

Fetch it by URL: GET /api/v1/registry/personamanagmentlayer-pcl-openapi-expert/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.