Index of every page on this site: llms.txt
All skills
wshobson avatar

/openapi-spec-generation

@4220308
by Seth Hobsonwshobson/agents43k stars
4,518
Run it yourself

Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance.

Use this Skill: https://skilld.dev/gh/wshobson/agents/openapi-spec-generation

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈55 tokens for metadata: the name and description. ≈449 when used: this file. ≈5.9k more on demand in 2 files.

Description uses 2.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈221 characters, or 2.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

OpenAPI Spec Generation

Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.

When to Use This Skill

  • Creating API documentation from scratch
  • Generating OpenAPI specs from existing code
  • Designing API contracts (design-first approach)
  • Validating API implementations against specs
  • Generating client SDKs from specs
  • Setting up API documentation portals

Core Concepts

1. OpenAPI 3.1 Structure

openapi: 3.1.0
info:
  title: API Title
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get: ...
components:
  schemas: ...
  securitySchemes: ...

2. Design Approaches

Approach Description Best For
Design-First Write spec before code New APIs, contracts
Code-First Generate spec from code Existing APIs
Hybrid Annotate code, generate spec Evolving APIs

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.

Best Practices

Do's

  • Use $ref - Reuse schemas, parameters, responses
  • Add examples - Real-world values help consumers
  • Document errors - All possible error codes
  • Version your API - In URL or header
  • Use semantic versioning - For spec changes

Don'ts

  • Don't use generic descriptions - Be specific
  • Don't skip security - Define all schemes
  • Don't forget nullable - Be explicit about null
  • Don't mix styles - Consistent naming throughout
  • Don't hardcode URLs - Use server variables

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo5 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill provides comprehensive patterns and templates for generating OpenAPI specifications from code and design inputs. It facilitates the installation of well-known API documentation tools and generates configuration files from templates. It possesses an inherent attack surface for indirect prompt injection as it processes external code to generate documentation, which is its primary function.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 4220308. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 6 months ago
  • openapi
  • api-documentation
  • rest-api
  • sdk-generation
  • schema
  • design-first
  • api-contracts
  • yaml

README badge

README badge for wshobson/agents/openapi-spec-generation

Generates and maintains OpenAPI 3.1 specifications for RESTful APIs using design-first, code-first, or hybrid approaches. Includes templates for schemas, endpoints, security schemes, and error documentation, with patterns for validating API implementations against specs and generating client SDKs.

Generated from the current SKILL.md.

Does this skill generate OpenAPI specs from existing code, or do I write the spec first?
Both. The skill covers design-first (write spec before code), code-first (generate from existing code), and hybrid approaches (annotate code and generate).
What OpenAPI version does this target?
OpenAPI 3.1.0. The skill assumes 3.1 structure and patterns.
Can I use this to validate that my API implementation matches a spec?
Yes. The skill includes patterns for validating API implementations against OpenAPI specifications.
Does this skill help with SDK generation?
Yes. Generating client SDKs from OpenAPI specs is listed as a core use case, though the detailed implementation patterns are in the references/details.md file.

Generated from the current SKILL.md. These answers refresh after source changes.