openapi-expert
/openapi-expert
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.
- Author
- personamanagmentlayer ↗
- Repository
- pcl ↗
- Licence
- Apache-2.0
- Last repository change
- 10.09.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 4
No signals detected. Repository changed on 10.09.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
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.
Original author 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.
How it works
- Core Concepts
- Advanced Features
- Code Generation
- Validation
- Documentation Generation
- Best Practices
- Reference Documentation
- Resources
SKILL.md preview
---
name: openapi-expert
version: 1.1.0
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.
category: api
tags: [openapi, swagger, api-spec, rest, api-design, documentation]
allowed-tools:
- Read
- Write
- Edit
- Bash(openapi:*, swagger:*)
---
# OpenAPI Expert
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)
```yaml
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)
```yaml
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
```bash
# 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
```bash
# 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
```bash
# 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](references/BASIC_OPENAPI_SPECIFICATION.md)
## Resources
- OpenAPI Spec: https://spec.openapis.org/
- Swagger Editor: https://editor.swagger.io/
- OpenAPI Tools: https://openapi.tools/
- Stoplight Studio: https://stoplight.io/studio
Files in this package (2)
- SKILL.md 4 KB
- references/BASIC_OPENAPI_SPECIFICATION.md 7 KB
Versions
The database has no other skills named openapi-expert.
Database snapshot: 13.11.2026 · package version e542060dad0e (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95api-documentation-generator
Generate OpenAPI/Swagger specifications and API documentation from code or design. Use when creating API docs, generating OpenAPI specs, or documenting REST APIs. - 100openapi
OpenAPI/Swagger specification. Covers schema definition, paths, and documentation. Use for API documentation. USE WHEN: user mentions "OpenAPI", "Swagger", "API spec", "API documentation", "schema definition", "OpenAPI 3.0", "Swagger UI", asks about "how to write OpenAPI spec",… - 95openapi-specification-v2
OpenAPI (Swagger) 2.0 specification for describing REST APIs. Use when writing, validating, or interpreting Swagger 2.0 specs, generating clients/docs, or working with path/operation/parameter/response/schema/security definitions. - 100api-generating
Generate API endpoint code and documentation from specifications. Use when the user wants to create new API endpoints, generate route handlers, scaffold REST APIs, or produce OpenAPI/Swagger specs from code. - 100api-design-patterns
REST API design, versioning, error responses, pagination, OpenAPI conventions. Use when designing new API endpoints, reviewing API contracts, or setting up Swagger/OpenAPI documentation. - 90backend-openapi-documentation
Use this skill when the user says 'OpenAPI', 'Swagger', 'API documentation', 'spec-first', 'API spec', 'openapi.yaml', 'swagger.json', 'codegen', 'openapi-generator', 'API contract first'. This skill enforces spec-first API documentation with OpenAPI 3.x, code generation, and…