OpenParable
Skip to content
← Back to skills

Openapi Spec Generator

Development
openapi-spec-generator

Openapi Spec Generator is an Agent Skill for development published in the a5c-ai/babysitter repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Automated OpenAPI specification generation from code annotations, comments, and interface definitions

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/a5c-ai/babysitter/blob/HEAD/library/specializations/sdk-platform-development/skills/openapi-spec-generator/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/openapi-spec-generator, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

OpenAPI Spec Generator Skill

Overview

This skill automates the generation of OpenAPI 3.x specifications from code annotations, comments, and interface definitions. It parses source code to extract API endpoints, schemas, and documentation to produce comprehensive and accurate API specifications.

Capabilities

  • Parse code to extract API endpoints and schemas from annotations
  • Generate OpenAPI 3.x specifications in YAML or JSON format
  • Validate spec completeness and correctness against OpenAPI standards
  • Auto-update specs from code changes with incremental generation
  • Support multiple frameworks (Express, FastAPI, Spring, ASP.NET, etc.)
  • Extract request/response schemas from TypeScript types, Python type hints, Go structs
  • Generate examples from code-level documentation

Target Processes

  • API Design Specification
  • API Documentation System
  • SDK Code Generation Pipeline

Integration Points

  • Code analysis tools (AST parsers)
  • Schema validators (Spectral, openapi-spec-validator)
  • Swagger/OpenAPI tooling ecosystem
  • IDE extensions for spec preview

Input Requirements

  • Source code with API route definitions
  • Annotation/decorator conventions used in the codebase
  • Target OpenAPI version (3.0.x or 3.1.x)
  • Output format preference (YAML/JSON)

Output Artifacts

  • OpenAPI specification file (openapi.yaml or openapi.json)
  • Validation report with any issues found
  • Schema extraction summary
  • Change diff from previous spec version (if applicable)

Usage Example

skill:
  name: openapi-spec-generator
  context:
    sourceDirectory: ./src/api
    framework: express
    outputFormat: yaml
    openapiVersion: "3.1.0"
    includeExamples: true

Best Practices

  1. Use consistent annotation patterns across the codebase
  2. Include JSDoc/docstrings for all endpoints
  3. Define reusable schema components
  4. Validate generated specs before publishing
  5. Version control generated specifications