openapi — Skillopedia

OpenAPI Overview OpenAPI Specification (OAS) 3.1 is the industry standard for describing HTTP APIs. It defines a machine-readable contract covering endpoints, request/response schemas, authentication, and error formats. OpenAPI 3.1 is a strict superset of JSON Schema Draft 2020-12, enabling full JSON Schema compatibility for data validation and type generation. When to use: Designing REST APIs, generating typed clients (TypeScript, Python, Go), producing interactive documentation, validating request/response payloads, contract-first API development, API gateway configuration. When NOT to use:…

\n slug:\n type: string\n pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

\n```\n\n## Enums and Constants\n\n```yaml\nproperties:\n status:\n type: string\n enum: [active, inactive, suspended]\n version:\n type: string\n const: '1.0'\n```\n\n## Arrays\n\n```yaml\nproperties:\n tags:\n type: array\n items:\n type: string\n minItems: 1\n maxItems: 10\n uniqueItems: true\n matrix:\n type: array\n items:\n type: array\n items:\n type: number\n minItems: 3\n maxItems: 3\n coordinates:\n type: array\n prefixItems:\n - type: number\n - type: number\n items: false\n minItems: 2\n maxItems: 2\n```\n\n## Objects\n\n```yaml\nproperties:\n metadata:\n type: object\n properties:\n key:\n type: string\n required: [key]\n additionalProperties: false\n tags:\n type: object\n additionalProperties:\n type: string\n minProperties: 1\n maxProperties: 20\n config:\n type: object\n propertyNames:\n pattern: '^[a-z][a-zA-Z0-9]*

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

\n additionalProperties:\n type: string\n```\n\n## Nullable Fields (3.1)\n\nOpenAPI 3.1 removed `nullable: true`. Use type arrays instead:\n\n```yaml\nproperties:\n middleName:\n type: ['string', 'null']\n deletedAt:\n type: ['string', 'null']\n format: date-time\n bio:\n oneOf:\n - type: string\n maxLength: 500\n - type: 'null'\n```\n\n## Composition: allOf\n\nCombine schemas (intersection). All subschemas must validate:\n\n```yaml\ncomponents:\n schemas:\n BaseEntity:\n type: object\n properties:\n id:\n type: string\n format: uuid\n createdAt:\n type: string\n format: date-time\n updatedAt:\n type: string\n format: date-time\n required: [id, createdAt, updatedAt]\n\n User:\n allOf:\n - $ref: '#/components/schemas/BaseEntity'\n - type: object\n properties:\n name:\n type: string\n email:\n type: string\n format: email\n required: [name, email]\n```\n\n## Composition: oneOf\n\nExactly one subschema must validate (exclusive union):\n\n```yaml\ncomponents:\n schemas:\n PaymentMethod:\n oneOf:\n - $ref: '#/components/schemas/CreditCard'\n - $ref: '#/components/schemas/BankTransfer'\n - $ref: '#/components/schemas/DigitalWallet'\n\n CreditCard:\n type: object\n properties:\n type:\n type: string\n const: credit_card\n cardNumber:\n type: string\n expiryMonth:\n type: integer\n expiryYear:\n type: integer\n required: [type, cardNumber, expiryMonth, expiryYear]\n\n BankTransfer:\n type: object\n properties:\n type:\n type: string\n const: bank_transfer\n accountNumber:\n type: string\n routingNumber:\n type: string\n required: [type, accountNumber, routingNumber]\n\n DigitalWallet:\n type: object\n properties:\n type:\n type: string\n const: digital_wallet\n provider:\n type: string\n enum: [apple_pay, google_pay]\n token:\n type: string\n required: [type, provider, token]\n```\n\n## Composition: anyOf\n\nAt least one subschema must validate (inclusive union). Use when the value can match one or more schemas:\n\n```yaml\ncomponents:\n schemas:\n SearchFilter:\n anyOf:\n - type: object\n properties:\n name:\n type: string\n required: [name]\n - type: object\n properties:\n email:\n type: string\n format: email\n required: [email]\n```\n\n## Discriminator\n\nHints for code generators to select the correct schema branch. Only valid with `oneOf`, `anyOf`, or `allOf`:\n\n```yaml\ncomponents:\n schemas:\n Event:\n oneOf:\n - $ref: '#/components/schemas/UserCreatedEvent'\n - $ref: '#/components/schemas/OrderPlacedEvent'\n - $ref: '#/components/schemas/PaymentProcessedEvent'\n discriminator:\n propertyName: eventType\n mapping:\n user.created: '#/components/schemas/UserCreatedEvent'\n order.placed: '#/components/schemas/OrderPlacedEvent'\n payment.processed: '#/components/schemas/PaymentProcessedEvent'\n\n UserCreatedEvent:\n type: object\n properties:\n eventType:\n type: string\n userId:\n type: string\n required: [eventType, userId]\n\n OrderPlacedEvent:\n type: object\n properties:\n eventType:\n type: string\n orderId:\n type: string\n total:\n type: number\n required: [eventType, orderId, total]\n\n PaymentProcessedEvent:\n type: object\n properties:\n eventType:\n type: string\n paymentId:\n type: string\n amount:\n type: number\n required: [eventType, paymentId, amount]\n```\n\nEvery schema in the `oneOf`/`anyOf` must include the discriminator property. Without explicit `mapping`, schema names are used as discriminator values.\n\n## readOnly and writeOnly\n\nControl which properties appear in requests vs responses:\n\n```yaml\ncomponents:\n schemas:\n User:\n type: object\n properties:\n id:\n type: string\n format: uuid\n readOnly: true\n password:\n type: string\n format: password\n writeOnly: true\n name:\n type: string\n required: [id, name]\n```\n\n- `readOnly: true` — included in responses, excluded from requests\n- `writeOnly: true` — included in requests, excluded from responses\n\n## Default Values\n\n```yaml\nproperties:\n role:\n type: string\n enum: [admin, member, viewer]\n default: member\n isActive:\n type: boolean\n default: true\n pageSize:\n type: integer\n default: 20\n minimum: 1\n maximum: 100\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":7406,"content_sha256":"58a052ce857761a718654b38d91bfd689bf707e85fa72a28f456238b0261192f"},{"filename":"references/documentation.md","content":"---\ntitle: Documentation\ndescription: Swagger UI, Redoc, API documentation best practices, and interactive documentation setup\ntags: [swagger-ui, redoc, docs, documentation, api-docs, interactive]\n---\n\n# Documentation\n\n## Swagger UI\n\nInteractive API documentation that lets consumers explore and test endpoints directly in the browser.\n\n### Docker Setup\n\n```bash\ndocker run -p 8080:8080 -e SWAGGER_JSON=/app/openapi.yaml -v ./openapi.yaml:/app/openapi.yaml swaggerapi/swagger-ui\n```\n\n### Express Integration\n\n```ts\nimport express from 'express';\nimport swaggerUi from 'swagger-ui-express';\nimport spec from './openapi.json';\n\nconst app = express();\n\napp.use(\n '/api-docs',\n swaggerUi.serve,\n swaggerUi.setup(spec, {\n customCss: '.swagger-ui .topbar { display: none }',\n customSiteTitle: 'My API Documentation',\n }),\n);\n```\n\n### HTML Standalone\n\n```html\n\u003c!doctype html>\n\u003chtml lang=\"en\">\n \u003chead>\n \u003cmeta charset=\"UTF-8\" />\n \u003ctitle>API Docs\u003c/title>\n \u003clink\n rel=\"stylesheet\"\n href=\"https://unpkg.com/swagger-ui-dist/swagger-ui.css\"\n />\n \u003c/head>\n \u003cbody>\n \u003cdiv id=\"swagger-ui\">\u003c/div>\n \u003cscript src=\"https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js\">\u003c/script>\n \u003cscript>\n SwaggerUIBundle({\n url: '/openapi.yaml',\n dom_id: '#swagger-ui',\n presets: [\n SwaggerUIBundle.presets.apis,\n SwaggerUIBundle.SwaggerUIStandalonePreset,\n ],\n layout: 'StandaloneLayout',\n });\n \u003c/script>\n \u003c/body>\n\u003c/html>\n```\n\n## Redoc\n\nClean, three-panel documentation with excellent navigation and search.\n\n### HTML Standalone\n\n```html\n\u003c!doctype html>\n\u003chtml lang=\"en\">\n \u003chead>\n \u003cmeta charset=\"UTF-8\" />\n \u003ctitle>API Reference\u003c/title>\n \u003c/head>\n \u003cbody>\n \u003credoc spec-url=\"/openapi.yaml\">\u003c/redoc>\n \u003cscript src=\"https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\">\u003c/script>\n \u003c/body>\n\u003c/html>\n```\n\n### Redoc Configuration\n\n```html\n\u003credoc\n spec-url=\"/openapi.yaml\"\n hide-download-button\n required-props-first\n sort-props-alphabetically\n expand-responses=\"200,201\"\n path-in-middle-panel\n hide-hostname\n native-scrollbars\n>\u003c/redoc>\n```\n\n### CLI Build\n\nGenerate a zero-dependency static HTML file:\n\n```bash\nnpx @redocly/cli build-docs openapi.yaml -o docs/index.html\n```\n\n## Redocly CLI\n\nLinting, bundling, and previewing OpenAPI specs:\n\n```bash\nnpx @redocly/cli lint openapi.yaml\nnpx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml\nnpx @redocly/cli preview-docs openapi.yaml\n```\n\n### Redocly Configuration\n\nCreate a `redocly.yaml` for project-wide rules:\n\n```yaml\nextends:\n - recommended\n\nrules:\n operation-operationId: error\n operation-summary: warn\n no-path-trailing-slash: error\n no-ambiguous-paths: error\n tag-description: warn\n info-contact: warn\n no-unused-components: warn\n```\n\n## Documentation Best Practices\n\n### Descriptions\n\nWrite concise, actionable descriptions on every element:\n\n```yaml\npaths:\n /users:\n get:\n summary: List users\n description: >\n Returns a paginated list of users. Results are sorted by creation date\n (newest first). Use query parameters to filter by role or status.\n parameters:\n - name: role\n in: query\n description: Filter users by their assigned role\n schema:\n $ref: '#/components/schemas/UserRole'\n```\n\n### Examples\n\nProvide realistic examples at multiple levels:\n\n```yaml\ncomponents:\n schemas:\n User:\n type: object\n properties:\n id:\n type: string\n format: uuid\n example: 550e8400-e29b-41d4-a716-446655440000\n name:\n type: string\n example: Jane Doe\n email:\n type: string\n format: email\n example: [email protected]\n required: [id, name, email]\n\npaths:\n /users/{userId}:\n get:\n responses:\n '200':\n description: User details\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/User'\n examples:\n admin:\n summary: Admin user\n value:\n id: 550e8400-e29b-41d4-a716-446655440000\n name: Jane Doe\n email: [email protected]\n role: admin\n member:\n summary: Regular member\n value:\n id: 7c9e6679-7425-40de-944b-e07fc1f90ae7\n name: John Smith\n email: [email protected]\n role: member\n```\n\n### Tags and Grouping\n\nOrganize operations into logical groups:\n\n```yaml\ntags:\n - name: Authentication\n description: Login, logout, and token management\n - name: Users\n description: User CRUD operations and profile management\n - name: Organizations\n description: Organization management and membership\n\npaths:\n /auth/login:\n post:\n tags: [Authentication]\n operationId: login\n /users:\n get:\n tags: [Users]\n operationId: listUsers\n /organizations:\n get:\n tags: [Organizations]\n operationId: listOrganizations\n```\n\n### Error Documentation\n\nDocument error responses consistently across all operations:\n\n```yaml\ncomponents:\n responses:\n BadRequest:\n description: Invalid request parameters\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Error'\n example:\n code: BAD_REQUEST\n message: Invalid request body\n\n Unauthorized:\n description: Missing or invalid authentication\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Error'\n example:\n code: UNAUTHORIZED\n message: Authentication required\n\n Forbidden:\n description: Insufficient permissions\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Error'\n example:\n code: FORBIDDEN\n message: You do not have permission to access this resource\n\n NotFound:\n description: Resource not found\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Error'\n example:\n code: NOT_FOUND\n message: User not found\n\n RateLimited:\n description: Too many requests\n headers:\n Retry-After:\n schema:\n type: integer\n description: Seconds to wait before retrying\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Error'\n example:\n code: RATE_LIMITED\n message: Rate limit exceeded\n```\n\n### Multi-File Specs\n\nSplit large specs across files and bundle before publishing:\n\n```text\napi/\n openapi.yaml # Root document\n paths/\n users.yaml # /users and /users/{userId}\n auth.yaml # /auth/*\n schemas/\n user.yaml\n error.yaml\n parameters/\n pagination.yaml\n```\n\nReference external files:\n\n```yaml\npaths:\n /users:\n $ref: 'paths/users.yaml#/users'\n\ncomponents:\n schemas:\n User:\n $ref: 'schemas/user.yaml#/User'\n```\n\nBundle into a single file for distribution:\n\n```bash\nnpx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml\n```\n\n### Webhooks (3.1)\n\nOpenAPI 3.1 added top-level `webhooks` for documenting callback events:\n\n```yaml\nwebhooks:\n userCreated:\n post:\n summary: User created event\n operationId: onUserCreated\n requestBody:\n required: true\n content:\n application/json:\n schema:\n type: object\n properties:\n event:\n type: string\n const: user.created\n data:\n $ref: '#/components/schemas/User'\n timestamp:\n type: string\n format: date-time\n required: [event, data, timestamp]\n responses:\n '200':\n description: Webhook received\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":8041,"content_sha256":"16da5bf47f09fde5d2ba93820cec0ad15f78bdfb9b1aa06c2861f24fe041f550"},{"filename":"references/schema-design.md","content":"---\ntitle: Schema Design\ndescription: Paths, operations, request/response bodies, parameters, components, and $ref patterns for OpenAPI 3.1\ntags:\n [\n paths,\n operations,\n parameters,\n request-body,\n response,\n components,\n ref,\n schema,\n ]\n---\n\n# Schema Design\n\n## Document Structure\n\nEvery OpenAPI 3.1 document requires three top-level fields:\n\n```yaml\nopenapi: '3.1.0'\ninfo:\n title: My API\n version: 1.0.0\n description: A sample API\n contact:\n name: API Support\n email: [email protected]\n license:\n name: MIT\npaths: {}\n```\n\nOptional top-level fields: `servers`, `components`, `security`, `tags`, `externalDocs`, `webhooks`.\n\n## Servers\n\nDefine base URLs for different environments:\n\n```yaml\nservers:\n - url: https://api.example.com/v1\n description: Production\n - url: https://staging-api.example.com/v1\n description: Staging\n - url: http://localhost:3000/v1\n description: Local development\n```\n\nServer URLs support variables:\n\n```yaml\nservers:\n - url: https://{environment}.example.com/v1\n variables:\n environment:\n default: api\n enum: [api, staging, sandbox]\n```\n\n## Paths and Operations\n\nEach path defines operations (HTTP methods):\n\n```yaml\npaths:\n /users:\n get:\n operationId: listUsers\n summary: List all users\n tags: [users]\n parameters:\n - $ref: '#/components/parameters/PageParam'\n - $ref: '#/components/parameters/LimitParam'\n responses:\n '200':\n description: Paginated list of users\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/UserList'\n post:\n operationId: createUser\n summary: Create a new user\n tags: [users]\n requestBody:\n required: true\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/CreateUserRequest'\n responses:\n '201':\n description: User created\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/User'\n '422':\n $ref: '#/components/responses/ValidationError'\n\n /users/{userId}:\n get:\n operationId: getUser\n summary: Get a user by ID\n tags: [users]\n parameters:\n - $ref: '#/components/parameters/UserIdParam'\n responses:\n '200':\n description: User details\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/User'\n '404':\n $ref: '#/components/responses/NotFound'\n```\n\n## Parameters\n\nFour parameter locations: `path`, `query`, `header`, `cookie`.\n\n```yaml\ncomponents:\n parameters:\n UserIdParam:\n name: userId\n in: path\n required: true\n description: Unique user identifier\n schema:\n type: string\n format: uuid\n\n PageParam:\n name: page\n in: query\n required: false\n schema:\n type: integer\n minimum: 1\n default: 1\n\n LimitParam:\n name: limit\n in: query\n required: false\n schema:\n type: integer\n minimum: 1\n maximum: 100\n default: 20\n\n ApiVersionHeader:\n name: X-API-Version\n in: header\n required: false\n schema:\n type: string\n default: '2024-01'\n```\n\nPath parameters must always have `required: true`. Query parameters with array values use `style` and `explode`:\n\n```yaml\nparameters:\n - name: tags\n in: query\n schema:\n type: array\n items:\n type: string\n style: form\n explode: true\n```\n\n## Request Bodies\n\n```yaml\nrequestBody:\n required: true\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/CreateUserRequest'\n examples:\n basic:\n summary: Basic user\n value:\n name: Jane Doe\n email: [email protected]\n multipart/form-data:\n schema:\n type: object\n properties:\n avatar:\n type: string\n format: binary\n name:\n type: string\n required: [name]\n```\n\n## Responses\n\nEvery operation needs at least one response. Define reusable responses in components:\n\n```yaml\ncomponents:\n responses:\n NotFound:\n description: Resource not found\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Error'\n\n ValidationError:\n description: Validation failed\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/ValidationError'\n```\n\nResponse headers:\n\n```yaml\nresponses:\n '200':\n description: Success\n headers:\n X-Request-Id:\n schema:\n type: string\n format: uuid\n X-Rate-Limit-Remaining:\n schema:\n type: integer\n```\n\n## Components and $ref\n\nExtract reusable elements into `components`:\n\n```yaml\ncomponents:\n schemas:\n User:\n type: object\n properties:\n id:\n type: string\n format: uuid\n name:\n type: string\n minLength: 1\n maxLength: 255\n email:\n type: string\n format: email\n role:\n $ref: '#/components/schemas/UserRole'\n createdAt:\n type: string\n format: date-time\n required: [id, name, email, role, createdAt]\n\n CreateUserRequest:\n type: object\n properties:\n name:\n type: string\n minLength: 1\n maxLength: 255\n email:\n type: string\n format: email\n role:\n $ref: '#/components/schemas/UserRole'\n required: [name, email]\n\n UserRole:\n type: string\n enum: [admin, member, viewer]\n\n UserList:\n type: object\n properties:\n data:\n type: array\n items:\n $ref: '#/components/schemas/User'\n pagination:\n $ref: '#/components/schemas/Pagination'\n required: [data, pagination]\n\n Pagination:\n type: object\n properties:\n page:\n type: integer\n limit:\n type: integer\n total:\n type: integer\n required: [page, limit, total]\n\n Error:\n type: object\n properties:\n code:\n type: string\n message:\n type: string\n required: [code, message]\n```\n\n## Security Schemes\n\n```yaml\ncomponents:\n securitySchemes:\n BearerAuth:\n type: http\n scheme: bearer\n bearerFormat: JWT\n\n ApiKeyAuth:\n type: apiKey\n in: header\n name: X-API-Key\n\n OAuth2:\n type: oauth2\n flows:\n authorizationCode:\n authorizationUrl: https://auth.example.com/authorize\n tokenUrl: https://auth.example.com/token\n scopes:\n read:users: Read user data\n write:users: Modify user data\n\nsecurity:\n - BearerAuth: []\n```\n\nPer-operation security overrides the global setting:\n\n```yaml\npaths:\n /public/health:\n get:\n security: []\n responses:\n '200':\n description: Health check\n```\n\n## Tags\n\nGroup operations for documentation and code generation:\n\n```yaml\ntags:\n - name: users\n description: User management\n - name: auth\n description: Authentication and authorization\n```\n\n## operationId Best Practices\n\nUse verb-noun format for clear code generation output. Generated TypeScript functions map directly to `operationId` values:\n\n```yaml\npaths:\n /users:\n get:\n operationId: listUsers\n post:\n operationId: createUser\n /users/{userId}:\n get:\n operationId: getUser\n put:\n operationId: updateUser\n delete:\n operationId: deleteUser\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":7720,"content_sha256":"d758b3d1097b4d68a79dbe94f80fcb58edf83e959cd37734ee913432b4c34dea"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"OpenAPI","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"OpenAPI Specification (OAS) 3.1 is the industry standard for describing HTTP APIs. It defines a machine-readable contract covering endpoints, request/response schemas, authentication, and error formats. OpenAPI 3.1 is a strict superset of JSON Schema Draft 2020-12, enabling full JSON Schema compatibility for data validation and type generation.","type":"text"}]},{"type":"paragraph","content":[{"text":"When to use:","type":"text","marks":[{"type":"strong"}]},{"text":" Designing REST APIs, generating typed clients (TypeScript, Python, Go), producing interactive documentation, validating request/response payloads, contract-first API development, API gateway configuration.","type":"text"}]},{"type":"paragraph","content":[{"text":"When NOT to use:","type":"text","marks":[{"type":"strong"}]},{"text":" GraphQL APIs (use the GraphQL schema), gRPC services (use Protocol Buffers), WebSocket-only protocols, internal function calls that never cross a network boundary.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick Reference","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pattern","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Element","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Key Points","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Document root","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"openapi","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"info","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"paths","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"openapi: '3.1.0'","type":"text","marks":[{"type":"code_inline"}]},{"text":" required at top level","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Path item","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/resources/{id}","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Curly braces for path parameters","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Operation","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"get","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"post","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"put","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"delete","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"patch","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Each operation needs ","type":"text"},{"text":"operationId","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"responses","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Parameters","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"in: path|query|header|cookie","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Path params are always ","type":"text"},{"text":"required: true","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Request body","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"requestBody.content","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Keyed by media type (","type":"text"},{"text":"application/json","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Response","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"responses.200.content","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"At least one response required per operation","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Component ref","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"$ref: '#/components/schemas/Name'","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Reuse schemas, parameters, responses","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Schema types","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"type: string|number|integer|boolean|array|object","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Arrays support ","type":"text"},{"text":"type: [\"string\", \"null\"]","type":"text","marks":[{"type":"code_inline"}]},{"text":" in 3.1","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Composition","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"oneOf","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"anyOf","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"allOf","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Model polymorphism and intersection types","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Discriminator","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"discriminator.propertyName","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Hint for code generators with ","type":"text"},{"text":"oneOf","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"anyOf","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Security","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"securitySchemes","type":"text","marks":[{"type":"code_inline"}]},{"text":" + top-level ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Bearer, API key, OAuth2, OpenID Connect","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tags","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"tags","type":"text","marks":[{"type":"code_inline"}]},{"text":" on operations","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Group operations for documentation","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Type generation","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"openapi-typescript","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Zero-runtime TypeScript types from spec","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Typed fetch","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"openapi-fetch","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Type-safe HTTP client using generated types","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"React Query","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"openapi-react-query","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Type-safe React Query hooks from spec","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Schema-first","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"zod-openapi","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Generate OpenAPI documents from Zod schemas","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Common Mistakes","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mistake","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Correct Pattern","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Using ","type":"text"},{"text":"nullable: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" in 3.1","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"type: [\"string\", \"null\"]","type":"text","marks":[{"type":"code_inline"}]},{"text":" (3.0 syntax removed)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Missing ","type":"text"},{"text":"operationId","type":"text","marks":[{"type":"code_inline"}]},{"text":" on operations","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Always set unique ","type":"text"},{"text":"operationId","type":"text","marks":[{"type":"code_inline"}]},{"text":" for code generation","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Path parameter not in ","type":"text"},{"text":"required","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Path parameters are always required (","type":"text"},{"text":"required: true","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Inline schemas everywhere","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Extract to ","type":"text"},{"text":"components/schemas","type":"text","marks":[{"type":"code_inline"}]},{"text":" and use ","type":"text"},{"text":"$ref","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"allOf","type":"text","marks":[{"type":"code_inline"}]},{"text":" with conflicting ","type":"text"},{"text":"required","type":"text","marks":[{"type":"code_inline"}]},{"text":" fields","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Merge ","type":"text"},{"text":"required","type":"text","marks":[{"type":"code_inline"}]},{"text":" arrays; ","type":"text"},{"text":"allOf","type":"text","marks":[{"type":"code_inline"}]},{"text":" unions them","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Discriminator without shared property","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"All schemas in ","type":"text"},{"text":"oneOf","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"anyOf","type":"text","marks":[{"type":"code_inline"}]},{"text":" must include the discriminator property","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Empty ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":" on responses","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Every response needs a meaningful ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Using ","type":"text"},{"text":"type: object","type":"text","marks":[{"type":"code_inline"}]},{"text":" without ","type":"text"},{"text":"properties","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Always define ","type":"text"},{"text":"properties","type":"text","marks":[{"type":"code_inline"}]},{"text":" or use ","type":"text"},{"text":"additionalProperties","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Circular ","type":"text"},{"text":"$ref","type":"text","marks":[{"type":"code_inline"}]},{"text":" chains","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Break cycles with lazy resolution or restructure schemas","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mixing 3.0 and 3.1 syntax","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Choose one version; 3.1 drops ","type":"text"},{"text":"nullable","type":"text","marks":[{"type":"code_inline"}]},{"text":", changes ","type":"text"},{"text":"exclusiveMinimum","type":"text","marks":[{"type":"code_inline"}]},{"text":" to number","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Delegation","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"API design review","type":"text","marks":[{"type":"strong"}]},{"text":": Use ","type":"text"},{"text":"Task","type":"text","marks":[{"type":"code_inline"}]},{"text":" agent to audit spec completeness and consistency","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Type generation","type":"text","marks":[{"type":"strong"}]},{"text":": Use ","type":"text"},{"text":"Explore","type":"text","marks":[{"type":"code_inline"}]},{"text":" agent to find project-specific OpenAPI tooling config","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code review","type":"text","marks":[{"type":"strong"}]},{"text":": Delegate to ","type":"text"},{"text":"code-reviewer","type":"text","marks":[{"type":"code_inline"}]},{"text":" agent for generated client usage patterns","type":"text"}]}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"If the ","type":"text"},{"text":"typescript-patterns","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill is available, delegate advanced TypeScript typing questions to it.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"References","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Schema design: paths, operations, parameters, components, and $ref","type":"text","marks":[{"type":"link","attrs":{"href":"references/schema-design.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Data types: formats, composition, discriminators, and nullable","type":"text","marks":[{"type":"link","attrs":{"href":"references/data-types.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code generation: openapi-typescript, openapi-fetch, openapi-react-query, and Zod OpenAPI","type":"text","marks":[{"type":"link","attrs":{"href":"references/code-generation.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Documentation: Swagger UI, Redoc, and API docs best practices","type":"text","marks":[{"type":"link","attrs":{"href":"references/documentation.md","title":null}}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"openapi","author":"@skillopedia","source":{"stars":12,"repo_name":"agent-skills","origin_url":"https://github.com/oakoss/agent-skills/blob/HEAD/skills/openapi/SKILL.md","repo_owner":"oakoss","body_sha256":"0dbc828f2936d5f716ff64514ffe00211284be49a6b00557b34cd9c08f53526d","cluster_key":"ca877372916b449e60b21b18178fadf2de75c646cf4f4bd8b6c037d630e3a206","clean_bundle":{"format":"clean-skill-bundle-v1","source":"oakoss/agent-skills/skills/openapi/SKILL.md","attachments":[{"id":"2f543555-e1e3-5146-ae8d-1211d1c19542","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2f543555-e1e3-5146-ae8d-1211d1c19542/attachment.md","path":"references/code-generation.md","size":8120,"sha256":"31c9900e2ab528954684656bcd5ccca4f87ec4f75c37b02d0d1a9a3356c56014","contentType":"text/markdown; charset=utf-8"},{"id":"31423fa3-665a-5929-a540-9e466f5c52f8","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/31423fa3-665a-5929-a540-9e466f5c52f8/attachment.md","path":"references/data-types.md","size":7406,"sha256":"58a052ce857761a718654b38d91bfd689bf707e85fa72a28f456238b0261192f","contentType":"text/markdown; charset=utf-8"},{"id":"f38fb3b8-b798-5c20-87d0-3cd135422a78","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f38fb3b8-b798-5c20-87d0-3cd135422a78/attachment.md","path":"references/documentation.md","size":8041,"sha256":"16da5bf47f09fde5d2ba93820cec0ad15f78bdfb9b1aa06c2861f24fe041f550","contentType":"text/markdown; charset=utf-8"},{"id":"9b48efb6-1011-5e67-b82f-678348b6e392","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9b48efb6-1011-5e67-b82f-678348b6e392/attachment.md","path":"references/schema-design.md","size":7720,"sha256":"d758b3d1097b4d68a79dbe94f80fcb58edf83e959cd37734ee913432b4c34dea","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"e4ec789e54e7cf698b6aaacd5e64db4606c2bb5511b27910dc8effe3e944a9d6","attachment_count":4,"text_attachments":4,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/openapi/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"documents-office","category_label":"Documents"},"exact_dupes_collapsed_into_this":0},"license":"MIT","version":"v1","category":"documents-office","metadata":{"author":"oakoss","source":"https://spec.openapis.org/oas/v3.1.0","version":"1.1"},"import_tag":"clean-skills-v1","description":"OpenAPI 3.1 specification, schema design, and code generation. Use when designing REST APIs, generating TypeScript clients, or creating API documentation. Use for openapi, swagger, api-spec, schema, code-generation, api-docs, openapi-typescript, zod-openapi.","user-invocable":false}},"renderedAt":1782986255369}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.