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://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

ATTRIBUTION.md

Attribution

This folder is an unmodified copy of the Agent Skill "openapi-spec-generation", distributed by AutoGineer (https://autogineer.com/agent-skills).

The skill's own files are unmodified copies. AutoGineer is not affiliated with or endorsed by the author or the publisher.

Files added by AutoGineer

  • ATTRIBUTION.md: this file, written by AutoGineer

  • LICENSE: copied from LICENSE

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 or Seth Hobson.

Download ZIP

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