Building Openapi Spec From Code

We built this skill so you don't have to maintain a YAML file that diverges from your Java controllers or TypeScript services. If you're tired of the annotation tax, the documentation drift, and the endless cycle of "docs don't match code," this Pro skill automates the generation of OpenAPI specifications directly from your codebase. You write the implementation; we handle the spec.

The Annotation Tax and the Documentation Drift

Engineers know the feeling. You write a REST endpoint. It works. The client calls it. Then someone asks for the API documentation. You open the openapi.yaml file. You remember vaguely what the response schema looked like. You spend an hour updating the spec. Two weeks later, you refactor the endpoint to support a new query parameter. You forget to update the spec. The frontend breaks. The client complains. The blame game starts.

This is the cost of manual documentation. Even if you're disciplined, the friction of switching context from implementation to documentation leads to drift. A code-first approach is tempting because it keeps the spec close to the code ^[6]. But without automation, "code-first" often just means "code-first, docs-later," and "docs-later" rarely happens. The spec becomes a legacy artifact, maintained by someone who didn't write the code and doesn't understand the intent.

We see teams struggling with this daily. Developers complain that Swagger annotations feel like clutter in their Java classes ^[7]. They spend more time tweaking @Operation descriptions than writing business logic. The annotations accumulate, becoming stale the moment you commit. The result is a spec that is either ignored or maintained by a separate team that doesn't understand the code well enough to keep it accurate. This creates a disconnect between the API contract and the actual implementation, leading to integration failures and wasted engineering time.

What Manual Spec Maintenance Costs Your P99 and Your Team

Ignoring this drift isn't free. The cost isn't just the hours you spend updating YAML files; it's the downstream impact on your entire engineering organization.

Every hour you spend manually editing an OpenAPI spec is an hour you aren't shipping features. If you have 50 endpoints and you update one per week, that's 50 weeks of maintenance for a single release cycle. Multiply that by the number of services in your monolith or microservices mesh, and you're looking at dozens of engineering hours per sprint wasted on documentation tax. This is a direct drain on velocity. Your team is paid to build, not to maintain text files that should be derived from the code.

More critically, bad docs break downstream tools. If you use an SDK generator, a stale spec generates broken client libraries. Your frontend and mobile teams will start caching responses, hardcoding fields, or building workarounds for endpoints that "should" exist according to the docs but don't. This erodes trust in your API. When your docs lie, your engineers stop reading them. Once they stop reading, they start calling you on Slack to ask what the endpoint returns. Your P99 latency doesn't just include network time; it includes the "wait for the API owner to explain the schema" time.

If you're already investing in SDK generation, you need a spec that is guaranteed to match your code. Tools like the building-rest-api-sdk-generator rely on a single source of truth. If that source is a manually edited YAML file, you're building on sand. You need a workflow that ensures the spec is derived from the code, not the other way around. The api-documentation-pack can help you integrate the generated spec into a broader workflow, including validation, interactive docs, and deployment pipelines, but it all starts with a reliable spec source.

A Spring Boot Team's Migration to Automated Spec Generation

Imagine a fintech platform with 200 REST endpoints across five microservices. The team uses Spring Boot for the backend. For years, they maintained a single openapi.yaml file in the root of the repository. Every time a developer added a new endpoint, they were supposed to update the spec. In practice, they updated the spec only when they remembered, or when a QA bug report forced them to.

The result was a spec that was 90% accurate but 100% frustrating. Frontend developers would encounter a 422 Unprocessable Entity error and check the docs, only to find the validation rules listed in the spec didn't match the actual @Validated constraints in the controller. The team spent two weeks in a "documentation sprint," trying to align the YAML with the code. They realized they couldn't sustain this.

They switched to a code-first generation strategy. Instead of writing the spec, they added annotations to their controllers. They used tools to scan the codebase and generate the spec automatically. This approach is gaining traction; teams are using static analysis to detect endpoints, parameters, and response schemas directly from the code ^[3]. By generating the spec from the code, they eliminated the drift. The spec became a build artifact, updated every time the code changed.

This shift also resolved the annotation clutter debate. Instead of scattering annotations everywhere, they standardized on a specific set of decorators. They used GroupedOpenApi to organize public, admin, and internal endpoints. They configured the Swagger UI to expose only what was necessary. The result was a spec that was always current, and a documentation workflow that required zero manual intervention. The api-docs-generator-pack offers a similar automation mindset, covering automated API documentation workflows with OpenAPI spec generation, SDK creation, testing, and deployment.

What Changes Once the Spec Is Locked and Validated

When you install this skill, the friction disappears. You write your code. You add the necessary annotations. You run the generation script. The OpenAPI spec is produced. It's committed to source control. It's validated.

The skill provides a complete toolkit for both Spring Boot and NestJS projects. For Spring Boot, you get templates for pom.xml with the correct springdoc-openapi dependencies. You get an OpenApiConfig.java that uses GroupedOpenApi to define your API groups. You get a production-grade Controller.java demonstrating how to use @Tag, @Operation, @ApiResponses, @Schema, and @Parameter annotations effectively. The configuration supports customizers for fine-grained control over the generated documentation, ensuring your public API is polished while internal endpoints remain hidden.

For NestJS, you get nest-cli.json configured with the @nestjs/swagger plugin. You get a main.ts bootstrap with SwaggerModule setup. You get dto.ts and controller.ts examples showing how to use @ApiProperty, @ApiQuery, and complex filter parameters. The NestJS templates demonstrate how to leverage the classValidatorShim for automatic validation schema generation, reducing the need for manual schema definitions.

But generation isn't enough. You need validation. The skill includes a scripts/validate-spec.mjs script that validates the generated spec against the official OAS 3.1 JSON schema using ajv. This ensures your spec is syntactically correct and adheres to the OpenAPI Specification ^[1]. You also get a validators/spectral-rules.yaml ruleset that enforces best practices like unique operationIds, summary presence, and trailing slash checks. This catches issues your team might miss, such as missing descriptions or inconsistent naming. The Spectral ruleset is designed to catch common pitfalls that can break downstream consumers, ensuring your API contract is robust and reliable.

The skill also provides references. You get references/springdoc-annotations.md and references/nestjs-decorators.md as canonical guides for the annotations and decorators you'll use. You get references/oas-standards.md to understand the differences between OAS 3.1 and 3.2, and the structural requirements of the spec. The OAS 3.2 specification introduces significant improvements over 3.1, including better support for JSON Schema ^[2]. Understanding these differences is crucial for ensuring your generated spec is compatible with modern tools and consumers.

And you get examples. The examples/springboot-worked.yaml and examples/nestjs-worked.yaml files show you exactly what a generated spec looks like. You can use these to verify your output and understand the structure of the generated document. The examples demonstrate how the annotations and decorators translate into the final spec, providing a clear mapping between your code and the API contract.

What's in the building-openapi-spec-from-code Pack

We've packaged everything you need to automate OpenAPI spec generation into a single Pro skill. Here's the file manifest:

• skill.md — Orchestrator skill file that defines the workflow for generating OpenAPI specs from code, references all templates, references, scripts, and examples.
• templates/springboot/pom.xml — Maven dependencies for springdoc-openapi-starter-webmvc-api and springdoc-openapi-starter-webmvc-ui.
• templates/springboot/application.yml — Springdoc configuration for API docs path, Swagger UI, package scanning, and API groups.
• templates/springboot/OpenApiConfig.java — Java configuration class using GroupedOpenApi to define public, admin, and internal API groups with customizers.
• templates/springboot/Controller.java — Production-grade REST controller demonstrating @Tag, @Operation, @ApiResponses, @Schema, and @Parameter annotations.
• templates/nestjs/nest-cli.json — NestJS CLI configuration for @nestjs/swagger plugin with classValidatorShim and introspectComments.
• templates/nestjs/main.ts — NestJS bootstrap with SwaggerModule setup, DocumentBuilder config, and plugin metadata loading.
• templates/nestjs/dto.ts — DTO class demonstrating @ApiProperty, @ApiPropertyOptional, enums, arrays, and nested object schemas.
• templates/nestjs/controller.ts — NestJS controller demonstrating @ApiTags, @ApiQuery with enums/arrays, and complex filter parameters.
• references/springdoc-annotations.md — Canonical reference for Springdoc OpenAPI annotations including @Operation, @ApiResponses, @Schema, GroupedOpenApi, and @RouterOperation.
• references/nestjs-decorators.md — Canonical reference for NestJS Swagger decorators including @ApiProperty, @ApiQuery, DocumentBuilder options, and plugin metadata.
• references/oas-standards.md — Summary of OpenAPI 3.1/3.2 specifications, design-first vs code-first approaches, and key structural requirements.
• scripts/validate-spec.mjs — Executable Node.js script to validate an OpenAPI spec file against the official OAS 3.1 JSON schema using ajv.
• validators/spectral-rules.yaml — Spectral ruleset enforcing OpenAPI best practices like unique operationIds, summary presence, and trailing slash checks.
• tests/test-validator.sh — Test script that creates a malformed spec, runs the validator, and verifies non-zero exit code on failure.
• examples/springboot-worked.yaml — Worked example of a generated OpenAPI spec from the Spring Boot templates, showing real output structure.
• examples/nestjs-worked.yaml — Worked example of a generated OpenAPI spec from the NestJS templates, showing real output structure.

Install and Ship

Stop fighting documentation drift. Start shipping APIs with specs that are always accurate. Upgrade to Pro to install the building-openapi-spec-from-code skill and automate your OpenAPI generation today. The skill integrates seamlessly into your existing CI/CD pipeline, ensuring your specs are always up-to-date and validated. You can focus on building features, not maintaining text files.