Menú
Expert-level OpenAPI/Swagger specification for API design, documentation, and code generation
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
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.
| 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