Generate API Specifications and Documentation

This skill provides expertise in API design specification and documentation, with deep knowledge of REST principles, OpenAPI/Swagger specifications, GraphQL schemas, and modern API architecture patterns, producing comprehensive, developer-friendly specifications that balance technical precision with clarity. Core API design principles cover RESTful resource design (nouns not verbs for resources, e.g. /users not /getUsers, consistent HTTP methods, hierarchical resource relationships like /users/{id}/orders, plural collection names, and correct HTTP status codes) and URL structure/naming conventions mapping each CRUD operation to its HTTP method and path (GET list, GET by id, POST create, PUT full update, PATCH partial update, DELETE).

The OpenAPI specification structure covers a full template: info block (title, version, description, contact, license), server definitions for production and staging, paths with parameters (pagination, filtering enums), request/response schemas with validation constraints (format, maxLength, enum, default), reusable components (schemas, responses like BadRequest/Unauthorized, and securitySchemes), and a top-level security requirement. Error handling and response patterns define a consistent error response structure (error code, message, field-level details, timestamp, request ID) and a pagination response pattern (data array, pagination metadata with page/limit/total/totalPages, and HATEOAS-style links for self/next/last). Authentication and security specification covers JWT bearer auth (with a description of how to obtain and format the token) and API key auth for service-to-service communication, both defined as OpenAPI securitySchemes.

Versioning strategy covers URL-path versioning (/api/v1/, /api/v2/) and header-based versioning (an API-Version header parameter with an enum of supported versions and a default). Advanced patterns include webhook specifications (an event payload schema for notifications like user.created) and rate-limit headers (X-RateLimit-Limit and X-RateLimit-Remaining documented on success responses). Documentation best practices call for clear concise endpoint summaries, detailed parameter descriptions with examples, every possible response code and scenario documented, request/response examples for complex operations, authentication/scope requirements, rate limit documentation, SDK code examples in multiple languages, and Postman/curl examples for testing. Testing and validation guidance covers including request/response examples, test data sets, error scenarios and edge cases, performance expectations, validation rules and constraints, and documented idempotency behavior where applicable.

Use this skill when designing or documenting a REST API's specification - resource structure, OpenAPI schema, error format, authentication, and versioning strategy - before or during implementation. It is well suited to APIs that will be consumed by external developers or multiple internal teams needing a formal contract. It is not meant for GraphQL-only APIs with no REST surface (though GraphQL schema knowledge is referenced), or for a trivial internal script with no formal API contract needed.

Input: the API's resources, operations, and authentication/versioning requirements.

Output: a complete OpenAPI specification with paths, schemas, error responses, security schemes, and versioning strategy. Example resource endpoint structure:

GET    /api/v1/users              # List users
GET    /api/v1/users/{id}         # Get a specific user
POST   /api/v1/users              # Create a user
PATCH  /api/v1/users/{id}         # Partially update a user
DELETE /api/v1/users/{id}         # Delete a user

Produces OpenAPI 3.0.3-compliant YAML specifications compatible with standard API tooling (Swagger UI, code generators, Postman imports).

Backend and API teams designing or documenting a REST API contract, and teams that need a formal OpenAPI specification with consistent error handling, auth, and versioning before external or cross-team consumption.