Menu
Expert-level OpenAPI/Swagger specification for API design, documentation, and code generation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | openapi-expert |
| version | 1.0.0 |
| description | Expert-level OpenAPI/Swagger specification for API design, documentation, and code generation |
| category | api |
| tags | ["openapi","swagger","api-spec","rest","api-design","documentation"] |
| allowed-tools | ["Read","Write","Edit","Bash(openapi:*, swagger:*)"] |
Expert guidance for OpenAPI Specification (formerly Swagger) - industry-standard for describing RESTful APIs with automatic documentation and code generation.
openapi: 3.1.0
info:
title: Blog API
description: RESTful API for blog management
version: 1.0.0
contact:
name: API Support
email: support@example.com
license:
name: MIT
servers:
- url: https://api.example.com/v1
description: Production server
- url: https://staging-api.example.com/v1
description: Staging server
paths:
/posts:
get:
summary: List all posts
description: Returns a paginated list of blog posts
operationId: listPosts
tags:
- Posts
parameters:
- name: page
in: query
description: Page number
required: false
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
description: Items per page
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: status
in: query
schema:
type: string
enum: [draft, published]
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Post'
pagination:
$ref: '#/components/schemas/Pagination'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalError'
post:
summary: Create a new post
operationId: createPost
tags:
- Posts
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostCreate'
responses:
'201':
description: Post created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Post'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/posts/{postId}:
parameters:
- name: postId
in: path
required: true
description: Post ID
schema:
type: integer
format: int64
get:
summary: Get a post
operationId: getPost
tags:
- Posts
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Post'
'404':
$ref: '#/components/responses/NotFound'
put:
summary: Update a post
operationId: updatePost
tags:
- Posts
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostUpdate'
responses:
'200':
description: Post updated
content:
application/json:
schema:
$ref: '#/components/schemas/Post'
'404':
$ref: '#/components/responses/NotFound'
delete:
summary: Delete a post
operationId: deletePost
tags:
- Posts
security:
- bearerAuth: []
responses:
'204':
description: Post deleted
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
Post:
type: object
required:
- id
- title
- content
- author
- status
- createdAt
properties:
id:
type: integer
format: int64
readOnly: true
title:
type: string
minLength: 5
maxLength: 200
slug:
type: string
readOnly: true
content:
type: string
minLength: 10
author:
$ref: '#/components/schemas/User'
status:
type: string
enum: [draft, published]
default: draft
tags:
type: array
items:
type: string
maxItems: 10
createdAt:
type: string
format: date-time
readOnly: true
updatedAt:
type: string
format: date-time
readOnly: true
PostCreate:
type: object
required:
- title
- content
properties:
title:
type: string
minLength: 5
maxLength: 200
content:
type: string
minLength: 10
status:
type: string
enum: [draft, published]
default: draft
tags:
type: array
items:
type: string
PostUpdate:
type: object
properties:
title:
type: string
minLength: 5
maxLength: 200
content:
type: string
minLength: 10
status:
type: string
enum: [draft, published]
tags:
type: array
items:
type: string
User:
type: object
properties:
id:
type: integer
format: int64
email:
type: string
format: email
name:
type: string
Pagination:
type: object
properties:
page:
type: integer
limit:
type: integer
total:
type: integer
totalPages:
type: integer
Error:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
details:
type: array
items:
type: object
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ValidationError:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT authentication
apiKey:
type: apiKey
in: header
name: X-API-Key
security:
- bearerAuth: []
webhooks:
postCreated:
post:
summary: Post created webhook
operationId: onPostCreated
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Post'
responses:
'200':
description: Webhook received
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
# 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
# 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
# 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
Type-safe SQL ORM for TypeScript with zero runtime overhead
This skill should be used when users need to create, modify, optimize, or troubleshoot GitHub Actions CI/CD workflows. Use when users ask about automating builds, tests, deployments, or any GitHub Actions-related tasks. Triggers include requests like "create a CI workflow", "deploy to AWS", "automate testing", "setup GitHub Actions", or when debugging workflow failures.
OpenAPI Specification 3.2 — write and interpret OpenAPI descriptions (OAD), paths, operations, parameters, request/response, schema (JSON Schema 2020-12), security, and extensions. Use when authoring or validating OpenAPI 3.2 documents.
Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.
Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines, dependsOn, caching, remote cache, the "turbo" CLI, --filter, --affected, CI optimization, environment variables, internal packages, monorepo structure/best practices, and boundaries. Use when user: configures tasks/workflows/pipelines, creates packages, sets up monorepo, shares code between apps, runs changed/affected packages, debugs cache, or has apps/packages directories.
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.