playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / openapi-spec-generator

openapi-spec-generator skill

/skills/15-api-development/openapi-spec-generator

This skill helps you generate production-ready OpenAPI specs and configurations with best practices for API design, validation, and tooling.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill openapi-spec-generator

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.1 KB
---
name: "openapi-spec-generator"
description: |
  Generate openapi spec generator operations. Auto-activating skill for API Development.
  Triggers on: openapi spec generator, openapi spec generator
  Part of the API Development skill category. Use when working with APIs or building integrations. Trigger with phrases like "openapi spec generator", "openapi generator", "openapi".
allowed-tools: "Read, Write, Edit, Bash(curl:*), Grep"
version: 1.0.0
license: MIT
author: "Jeremy Longshore <[email protected]>"
---

# Openapi Spec Generator

## Overview

This skill provides automated assistance for openapi spec generator tasks within the API Development domain.

## When to Use

This skill activates automatically when you:
- Mention "openapi spec generator" in your request
- Ask about openapi spec generator patterns or best practices
- Need help with api development skills covering rest, graphql, openapi, authentication, and api design patterns.

## Instructions

1. Provides step-by-step guidance for openapi spec generator
2. Follows industry best practices and patterns
3. Generates production-ready code and configurations
4. Validates outputs against common standards

## Examples

**Example: Basic Usage**
Request: "Help me with openapi spec generator"
Result: Provides step-by-step guidance and generates appropriate configurations


## Prerequisites

- Relevant development environment configured
- Access to necessary tools and services
- Basic understanding of api development concepts


## Output

- Generated configurations and code
- Best practice recommendations
- Validation results


## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| Configuration invalid | Missing required fields | Check documentation for required parameters |
| Tool not found | Dependency not installed | Install required tools per prerequisites |
| Permission denied | Insufficient access | Verify credentials and permissions |


## Resources

- Official documentation for related tools
- Best practices guides
- Community examples and tutorials

## Related Skills

Part of the **API Development** skill category.
Tags: api, rest, graphql, openapi, swagger

Overview

This skill automates generation and validation of OpenAPI specifications to accelerate API development and integration work. It provides guided, production-ready OpenAPI operations, configuration snippets, and validation feedback tailored to REST and GraphQL endpoints. Use it to standardize API contracts and speed up client/server scaffolding.

How this skill works

The skill inspects your API description, routes, schemas, security requirements, and example payloads to produce a structured OpenAPI (v3) document. It applies industry best practices, generates reusable components (schemas, parameters, responses), and runs validation checks against common linters and spec validators. It can output YAML or JSON, include auth flows, and suggest versioning and documentation hints.

When to use it

  • Starting a new API to produce a canonical contract for clients and servers
  • Converting route code or existing docs into a formal OpenAPI v3 spec
  • Adding authentication schemes (OAuth2, API keys, JWT) into the spec
  • Generating mock servers, client SDKs, or API docs from a spec
  • Validating and linting an existing OpenAPI document before release

Best practices

  • Describe request/response schemas as reusable components to avoid duplication
  • Include examples and error response schemas for each operation
  • Declare securitySchemes centrally and reference them per operation
  • Use semantic versioning in the spec info and keep changelogs for breaking changes
  • Validate generated specs with a linter and an OpenAPI validator before publishing

Example use cases

  • Generate a complete OpenAPI YAML from annotated Flask/FastAPI routes to bootstrap client generation
  • Convert an existing collection of endpoint notes into a standardized OpenAPI v3 document
  • Add OAuth2 password or client credentials flows and produce sample curl calls
  • Create mock server definitions and example responses for frontend integration testing
  • Produce API documentation pages by exporting the generated spec to Redoc or Swagger UI

FAQ

What OpenAPI version does this generate?

It targets OpenAPI v3 (3.x) by default, with options to output YAML or JSON and follow v3 conventions for components and securitySchemes.

Can it include authentication and examples?

Yes. The skill can embed security schemes (OAuth2, API key, JWT) and attach request/response examples to operations and schemas.