# Generate Reliable OpenAPI 3.1 Specifications

Incomplete API contracts cause integration errors and weak documentation. This skill creates OpenAPI 3.1 specifications using design-first, code-first, validation, and SDK generation patterns.

## Install

```bash
npx skillstore add sickn33/openapi-spec-generation
```

## Metadata

- Status: approved
- Slug: sickn33-openapi-spec-generation
- Skillstore revision: r2
- Version status: missing
- Tree hash: 1039d7c1aeb7aabeac6740425aae2176d5f88a7cbfd764da8ac5bc388cb2cf1e
- Author: sickn33
- GitHub username: sickn33
- License: MIT
- Repository: https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/openapi-spec-generation
- Ref: 81e05e636292629114b76cbb3922fbe57672fc02
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: network, external\_commands
- Quality score: 78
- Quality tier: bronze
- Public page: https://skillstore.pages.dev/skills/sickn33-openapi-spec-generation
- Manifest: https://skillstore.pages.dev/api/skills/sickn33-openapi-spec-generation/manifest

## Capabilities

- Creates OpenAPI 3.1 contracts with paths, operations, schemas, parameters, responses, examples, and security schemes.
- Maps FastAPI and tsoa application structures into code-first OpenAPI generation patterns.
- Defines reusable components for pagination, errors, authentication, and common request or response models.
- Configures Spectral and Redocly rules for specification linting, bundling, and documentation previews.
- Prepares OpenAPI Generator workflows for TypeScript, Python, and Go client SDKs.

## Use Cases

- Design a New API Contract: Create a complete OpenAPI 3.1 contract before implementation, including resources, errors, authentication, examples, and pagination.
- Document an Existing Service: Translate FastAPI or TypeScript endpoint definitions into a consistent specification with reusable components.
- Standardize Delivery Checks: Define linting, bundling, documentation, and SDK generation steps for an API release pipeline.

## Prompt Templates

### Draft a Basic Contract

```
Create an OpenAPI 3.1 specification for [API purpose]. Include these endpoints: [list]. Ask for any missing models, errors, or authentication requirements.
```

### Convert Existing Endpoints

```
Review the supplied [FastAPI or tsoa] code and derive an OpenAPI 3.1 contract. Identify undocumented responses, inconsistent models, and missing security definitions.
```

### Harden an API Contract

```
Audit this OpenAPI 3.1 contract for reusable components, complete errors, examples, pagination, operation IDs, authentication, and schema constraints. Propose prioritized corrections.
```

### Plan Validation and SDK Delivery

```
Design a validation and SDK generation workflow for this specification. Include Spectral, Redocly, release checks, and clients for [target languages].
```

## Limitations

- Requires endpoint behavior, data models, authentication rules, and error details from the user or supplied code.
- Uses placeholder domains and sample data that must be replaced before production use.
- Does not execute validators or generators unless the user requests execution and the required tools are available.
- Cannot prove implementation compliance without runtime tests or contract testing against the deployed API.

## Best Practices

- Provide real endpoint behavior, models, error cases, authentication rules, and examples before generating the contract.
- Reuse schemas, parameters, and responses through components to prevent inconsistent definitions.
- Run linting, bundling, and contract tests before publishing documentation or generated SDKs.

## Anti Patterns

- Do not keep placeholder URLs, identities, or sample values in a production specification.
- Do not omit error responses, security requirements, or schema constraints to shorten the contract.
- Do not generate SDKs from an unvalidated or outdated specification.

## Security Audit

- Audited at: 2026-08-04T16:53:40.292\+00:00
- Summary: All 21 static findings are false positives. The URLs are documentation examples, the reconnaissance matches are ordinary schema terms, and the backticks mark Markdown file paths rather than executable commands.

## Stats

- Views: 114
- Downloads: 17
- Favorites: 0
- Popularity score: 0