openapi-spec-generation

Generates and maintains versioned OpenAPI 3.1 contracts for NestJS REST APIs with validated DTOs.

Updated Apr 4, 2026
One-click install
npx skills add https://github.com/SleyiW/iWana-neXt --skill openapi-spec-generation-sleyiw
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: openapi-spec-generation
Source: https://github.com/SleyiW/iWana-neXt/tree/main/.agents/skills/openapi-spec-generation
Command: npx skills add https://github.com/SleyiW/iWana-neXt --skill openapi-spec-generation-sleyiw

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Keeping OpenAPI specifications synchronized with actual NestJS backend implementations is error-prone: contracts drift from DTO validation, security requirements go undocumented, and breaking changes ship without versioning or traceability. ## Core Features & Use Cases - Contract-Code Alignment: Ensures the OpenAPI spec reflects real DTO validation, pipes, nullable fields, enums, and authentication requirements declared in the backend. - Versioned REST Governance: Enforces route versioning, breaking-change detection, consistent pagination/filtering conventions, and documented error structures across bounded contexts. - Security & Multi-Tenant Documentation: Declares bearer auth, 401/403 responses, and tenant context rules without leaking internal schema or infrastructure details. - Use Case: When adding a new endpoint to a NestJS module, use this Skill to update the OpenAPI spec so it matches the DTOs, declares security schemes, includes PII-free examples, and records the contractual change in the execution report or ADR. ## Quick Start Ask the agent to review the new endpoint you just added in the NestJS backend and update the OpenAPI specification so the contract matches the DTO validation and security requirements.

Frequently Asked Questions about openapi-spec-generation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I keep an OpenAPI spec in sync with a NestJS backend?

Review each endpoint's decorators, DTOs, and validation pipes, then update the spec so required fields, enums, nullable types, and security schemes match the real code. This Skill provides a checklist and heuristics to detect drift between implementation and contract.

How to document authentication and errors in OpenAPI 3.1?

Declare security schemes such as bearer JWT in components, apply them per operation, and document 401 and 403 responses where they apply. Error responses should use a consistent schema with code, message, and optional field-level details.

What should an OpenAPI contract include for a multi-tenant API?

The contract should reflect the authenticated tenant context when it affects behavior and document any visible headers or rules for consumers. It must not expose internal infrastructure details such as database schemas or table names.

When does an API change require a new version in OpenAPI?

Any breaking change to routes, payloads, or response structures requires clear versioning and a documented note about impacted consumers. Non-breaking additive changes can ship within the existing version with traceability in an ADR or execution report.

Why should OpenAPI examples avoid real user data?

Examples with real emails, phone numbers, or documents leak PII into published documentation and repositories. Use synthetic placeholder values that still demonstrate the expected formats and validation constraints.