openapi-generator
npx machina-cli add skill a5c-ai/babysitter/openapi-generator --openclawFiles (1)
SKILL.md
2.4 KB
OpenAPI Generator Skill
Generates OpenAPI specifications from code annotations, legacy APIs, or runtime analysis, with schema inference and documentation generation.
Purpose
Enable API documentation for:
- Spec generation from code
- Schema inference
- Example generation
- Validation rule extraction
- Documentation generation
Capabilities
1. Spec Generation from Code Annotations
- Parse JSDoc/Swagger annotations
- Extract from decorators
- Process code comments
- Support multiple languages
2. Schema Inference
- Infer from TypeScript types
- Extract from runtime samples
- Build from database models
- Derive from existing payloads
3. Example Generation
- Generate realistic examples
- Create edge case samples
- Produce validation examples
- Build test fixtures
4. Validation Rule Extraction
- Extract validation constraints
- Document required fields
- Map format rules
- Export enum values
5. Versioning Support
- Track API versions
- Generate diff between versions
- Document breaking changes
- Support multiple versions
6. Documentation Generation
- Generate Swagger UI
- Create ReDoc pages
- Export to Postman
- Build developer portals
Tool Integrations
| Tool | Language | Integration Method |
|---|---|---|
| Swagger Codegen | Multi | CLI |
| OpenAPI Generator | Multi | CLI |
| springdoc | Java/Spring | Library |
| NSwag | .NET | CLI |
| tsoa | TypeScript | CLI |
| FastAPI | Python | Auto |
Output Schema
{
"generationId": "string",
"timestamp": "ISO8601",
"specification": {
"openapi": "string",
"info": {},
"paths": {},
"components": {}
},
"artifacts": {
"specFile": "string",
"docsUrl": "string",
"postmanCollection": "string"
},
"coverage": {
"endpoints": "number",
"documented": "number",
"schemasGenerated": "number"
}
}
Integration with Migration Processes
- api-modernization: Spec generation
- documentation-migration: API docs
Related Skills
api-inventory-scanner: Endpoint discoveryapi-compatibility-analyzer: Version comparison
Related Agents
api-modernization-architect: API designdocumentation-migration-agent: Doc generation
Source
git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/specializations/code-migration-modernization/skills/openapi-generator/SKILL.mdView on GitHub Overview
OpenAPI Generator Skill creates OpenAPI specifications from code annotations, legacy APIs, or runtime analysis. It supports schema inference, example generation, validation rule extraction, and comprehensive documentation generation to streamline API docs.
How This Skill Works
It parses JSDoc, decorators, and runtime samples to infer schemas, then assembles the OpenAPI document with paths, components, and info. It can generate Swagger UI, ReDoc pages, and export Postman collections, while tracking API versions and diffs.
When to Use It
- Document a codebase with annotations or decorators to produce an OpenAPI spec.
- Migrate a legacy API by inferring schemas from existing endpoints and runtime behavior.
- Generate realistic examples and edge-case samples for tests and client docs.
- Extract validation rules and required fields for accurate client contracts.
- Manage multiple API versions and publish diffs and breaking-change notes.
Quick Start
- Step 1: Point the generator at your codebase, legacy API, or runtime samples.
- Step 2: Run the tool to produce the OpenAPI specification and docs.
- Step 3: Validate the schemas, review the docs, and publish to your portal or Postman.
Best Practices
- Keep code annotations in sync with the OpenAPI schema to reduce drift.
- Validate inferred schemas against real request/response data and adjust types as needed.
- Version specs consistently and document breaking changes for downstream consumers.
- Use diverse example payloads to cover common and edge-case scenarios.
- Publish outputs to multiple formats (Swagger UI, ReDoc, Postman) for broader consumption.
Example Use Cases
- Generate an OpenAPI spec from TypeScript Express handlers with JSDoc comments.
- Infer schemas from database models to bootstrap API documentation.
- Migrate a legacy REST API by analyzing runtime traffic and responses.
- Create Swagger UI and ReDoc pages for a developer portal.
- Export the OpenAPI spec to a Postman collection for testing and collaboration.
Frequently Asked Questions
Add this skill to your agents
