AutoGineer
Generated banner for Openapi Spec Generation
Generated logo for Openapi Spec Generation

Openapi Spec Generation

Seth HobsonCommunityCreated by Seth Hobson

  • Skill
  • Tool integration
  • Software development
  • MIT
  • Low risk
Download ZIP

From the author

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.
— the description by Seth Hobson

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to managing OpenAPI 3.1 specifications. It covers multiple development methodologies, including design-first, code-first, and hybrid approaches. It offers templates for API structures, schema definitions, and best practices for documentation, security, and versioning to ensure consistent and compliant API contracts.

What it does

  • Defines OpenAPI 3.1 structures for RESTful services
  • Supports design-first, code-first, and hybrid development workflows
  • Provides templates for API documentation and schema management
  • Outlines best practices for versioning and security definitions
  • Facilitates API contract validation and SDK generation

When to use it

  • When starting a new API project from scratch
  • When generating documentation from existing codebases
  • When establishing a design-first contract for team collaboration
  • When ensuring API implementations remain compliant with defined specs

Advantages

  • Promotes consistency through reusable schemas and references
  • Improves developer experience with detailed examples and error documentation
  • Supports automated workflows for SDK and documentation generation
  • Ensures clear API versioning and security standards

Usage examples

“Create an OpenAPI 3.1 specification template for a user management API.”
The agent generates a YAML structure including info, servers, tags, and path definitions with reusable components for users and profiles.
“How do I generate an OpenAPI spec from a FastAPI application?”
The agent provides a code-first example using Pydantic models and FastAPI decorators to automatically produce an OpenAPI-compliant schema.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/wshobson/openapi-spec-generation/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip openapi-spec-generation.zip -d .agents/skills

Documentation by Seth Hobson

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
ApproachDescriptionBest For
Design-FirstWrite spec before codeNew APIs, contracts
Code-FirstGenerate spec from codeExisting APIs
HybridAnnotate code, generate specEvolving 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

Files

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

What our scanner noticed· Low risk

  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Seth Hobson
Publisher
Seth Hobson (Community)
Source
wshobson/agents · plugins/documentation-generation/skills/openapi-spec-generation · commit 4bde316
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Seth Hobson.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download openapi-spec-generation.zip