writing-openapi-specs
Writing OpenAPI Specs
Reference for OpenAPI best practices and conventions. This skill provides guidance on taste, conventions, and grey areas not covered by the OpenAPI specification itself.
When to Use This Skill
- Writing a new OpenAPI specification
- Improving operation naming and organization
- Expressing complex data types (enums, polymorphism, nullable)
- Handling file uploads, streaming, or server-sent events
- Making specs more code-gen friendly
- Understanding reusability patterns (components vs inline)
Core Principles
Naming Conventions
Operation IDs: Use lowercase with underscores, following resource_action pattern:
More from speakeasy-api/skills
extract-openapi-from-code
Use when extracting or generating an OpenAPI spec from existing API code. Triggers on "extract OpenAPI", "code first", "generate spec from code", "FastAPI OpenAPI", "Spring Boot OpenAPI", "NestJS swagger", "Django OpenAPI", "Flask OpenAPI", "Rails swagger", "Laravel OpenAPI", "existing API code
71speakeasy-context
Speakeasy workflow: run 'agent context' FIRST, do task, run 'agent feedback' LAST. Triggers on speakeasy, SDK, OpenAPI.
52diagnose-generation-failure
Use when SDK generation failed or seeing errors. Triggers on "generation failed", "speakeasy run failed", "SDK build error", "workflow failed", "Step Failed", "why did generation fail
51manage-openapi-overlays
Use when creating, applying, or validating overlay files including x-speakeasy extensions. Covers overlay syntax, JSONPath targeting, retries, pagination, naming, grouping, open enums, global headers, custom security. Triggers on "create overlay", "apply overlay", "overlay file", "x-speakeasy", "add extension", "configure retries", "add pagination", "overlay for retries".
50customize-sdk-hooks
|
49generate-mcp-server
Use when generating an MCP server from an OpenAPI spec with Speakeasy. Triggers on "generate MCP server", "MCP server", "Model Context Protocol", "AI assistant tools", "Claude tools", "speakeasy MCP", "mcp-typescript
49