skills.rest
DeepSpaceCartel
DeepSpaceCartelOFFICIAL
Explore all skills by this author →
WebsiteGitHub

openapi

Write and review OpenAPI 3.1/3.2 descriptions of HTTP APIs.

Updated Sep 9, 2026
Search Tags:#api design#openapi#swagger#rest api#json schema#http api#api contract
One-click install
npx skills add https://github.com/DeepSpaceCartel/skills --skill openapi-deepspacecartel
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: openapi
Source: https://github.com/DeepSpaceCartel/skills/tree/main/skills/openapi
Command: npx skills add https://github.com/DeepSpaceCartel/skills --skill openapi-deepspacecartel

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Writing an OpenAPI description that stays accurate, complete, and consistent with the running service is hard: teams conflate spec and API versions, skip error responses, duplicate schemas, and let the contract drift from the code. This Skill provides the rules and reference material to author and review OpenAPI 3.1/3.2 documents correctly. ## Core Features & Use Cases - Document structure guidance: Covers the document skeleton (openapi, info, servers, paths, components), operations, parameters, request bodies, and responses, including 3.2 additions like the query method, additionalOperations, querystring, and streaming media types. - Schema and component reuse: Explains how 3.1+ reuses JSON Schema 2020-12, plus $ref, components, discriminator-based polymorphism, and paging envelope patterns. - Security and navigation: Details security schemes (apiKey, http, OAuth2, OIDC, mutualTLS), global vs per-operation security, tags, webhooks, and callbacks. - Use Case: When designing a new REST endpoint in a Fastify or Spring service, use this Skill to define the operation contract with a stable operationId, complete 4xx/5xx responses, and reusable component schemas, then wire the generated document into CI so contract drift fails the build. ## Quick Start Use the openapi skill to write an OpenAPI 3.2 description for my widget CRUD API with bearer auth and full error responses.

Frequently Asked Questions about openapi

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an OpenAPI 3.2 description for a REST API?▼

Start with the document skeleton: the openapi spec version, info with your API's title and version, servers, paths, and components. Define each operation with a unique stable operationId, declare all parameters and request bodies, and document every reachable response status including 4xx and 5xx errors.

What is the difference between OpenAPI 3.0 and 3.1 schemas?▼

OpenAPI 3.1 and 3.2 schemas are JSON Schema 2020-12, while 3.0 used a dialect that only resembled JSON Schema. In 3.1+, $ref can carry sibling keywords, nullable is replaced by type arrays like ["string", "null"], and unevaluatedProperties handles closed composed objects.

How do I define security schemes in OpenAPI?▼

Declare schemes once under components.securitySchemes using types like apiKey, http, oauth2, openIdConnect, or mutualTLS, then apply them globally via the top-level security list. Override per operation as needed, and set security to an empty array for deliberately public endpoints.

Does OpenAPI 3.2 support streaming responses?▼

Yes, OpenAPI 3.2 adds streaming media types including text/event-stream, application/jsonl, application/json-seq, and multipart/mixed, described with an itemSchema. It also adds the query HTTP method and additionalOperations for non-standard verbs.

Why should operationId be unique and stable in OpenAPI?▼

The operationId names the generated client method, so it acts as the API of your generated SDK. Renaming or reusing an operationId silently breaks generated callers on the next regeneration, so keep it globally unique and stable across releases.

How do I keep an OpenAPI document in sync with my code?▼

For code-first frameworks like Fastify with TypeBox, Spring, or FastAPI, keep schemas on route definitions and serve the generated document at /openapi.json. Diff it in CI so an unintended contract change fails the build, and never hand-edit generated output.

Related Skills

Explore More Software Engineering Skills→
stephanjstephanj
9

api-designer

Design scalable REST and GraphQL API architectures with OpenAPI 3.1 specifications.

Community
Advanced
fgarofalo56fgarofalo56
6

openapi-swagger

Design, document, generate, validate, and mock RESTful APIs with OpenAPI and Swagger.

Community
Advanced
ResgridResgrid
224

error-handling

Define Result-based error handling with RFC 9457 ProblemDetails for .NET 10 APIs.

Official
Intermediate
blockmaticblockmatic
88

TypeBox + Fastify

Build type-safe Fastify APIs with TypeBox schemas and OpenAPI generation.

Official
Advanced