skills.rest
earayu
earayuCOMMUNITY
Explore all skills by this author →
Website𝕏@earayuGitHub

openapi-spec-conventions

Structure OpenAPI specs, SDK generation, and sandbox proxy paths to prevent drift.

34|1|Updated Mar 17, 2026
Search Tags:#architecture#documentation#openapi#conventions#sandbox#api-design#sdk-generation
One-click install
npx skills add https://github.com/earayu/treadstone --skill openapi-spec-conventions
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: openapi-spec-conventions
Source: https://github.com/earayu/treadstone/tree/main/.agents/skills/openapi-spec-conventions
Command: npx skills add https://github.com/earayu/treadstone --skill openapi-spec-conventions

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Clarifies how to structure and evolve OpenAPI specs, SDK generation, and sandbox proxy path conventions to prevent drift.

Core Features & Use Cases

  • Defines and maintains the three-tier OpenAPI artifacts (full, public/SDK-focused, and runtime/docs) and their roles.
  • Standardizes sandbox proxy path conventions and operationId tagging to ensure consistent codegen and docs.
  • Provides guidance for updating tooling and docs when API routes or OpenAPI tags change.

Quick Start

Follow these conventions whenever adding or modifying API routes, regenerating the Python SDK, or updating sandbox proxy paths in docs.

Frequently Asked Questions about openapi-spec-conventions

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

FAQPage Schema
How do I prevent OpenAPI spec drift when updating API routes and generating SDKs?▼

Prevent OpenAPI spec drift by maintaining a three-tier spec structure, enforcing proper operationId tagging, and ensuring accurate sandbox proxy path merging across docs, SDKs, and runtime behavior.

What is the three-tier OpenAPI spec structure used for SDK generation and sandbox routing?▼

The three-tier OpenAPI spec structure consists of full, public/SDK-focused, and runtime/docs artifacts to standardize codegen and sandbox proxy path conventions for consistent API documentation.

How do I update sandbox proxy paths in OpenAPI documentation without breaking runtime behavior?▼

Update sandbox proxy paths by accurately merging sandbox runtime paths in docs and following standardized path conventions to ensure consistent runtime behavior and SDK generation.

Why does my Python SDK codegen fail after adding new OpenAPI operationId tags?▼

Python SDK codegen fails when OpenAPI operationId tagging conventions are not followed properly, causing drift between the public spec and the generated SDK code.

Do I need to regenerate the Python SDK every time I modify API routes in the OpenAPI spec?▼

Yes, you need to regenerate the Python SDK whenever modifying API routes to prevent drift between the OpenAPI spec, the SDK code, and the sandbox runtime paths.

Related Skills

Explore More Software Engineering Skills→
ather-techieather-techie
6

update-openapi

Synchronize OpenAPI specification files with TypeScript route definitions in Node.js.

Community
Intermediate
IntelliTectIntelliTect

run-code-generation

Orchestrate Coalesce code generation to regenerate TypeScript models and API clients after C# entity changes.

Official
Advanced
feasibleonefeasibleone
1

blong-rest

Implement REST APIs from OpenAPI specs within Blong's gateway.

Official
Intermediate
cardinalconseilscardinalconseils
3

api-docs

Detect API endpoints across frameworks and generate Markdown or OpenAPI docs.

Community
Advanced