swagger-docs-generator_skill

Overview

This skill generates a ready-to-use Swagger/OpenAPI documentation setup for Express REST APIs. It produces a TypeScript configuration file (swagger.ts) using swagger-ui-express and conforms to OpenAPI 3.x standards. The output is minimal, importable, and designed for immediate integration into an Express app.

How this skill works

When triggered, the skill emits a complete swagger.ts file that configures swagger-ui-express, mounts the Swagger UI endpoint, and bundles an OpenAPI 3.x JSON object or a path to the spec. The generated code includes TypeScript types, example metadata (info, servers, security), and an example paths object or hooks to load a paths file. The result can be dropped into a project and wired to the main Express server with minimal edits.

When to use it

• You want a quick Swagger UI endpoint for an existing Express REST API.
• Setting up API documentation during initial project scaffolding.
• Generating a consistent OpenAPI 3.x starter spec for teams to extend.
• Adding developer-friendly API docs for QA, frontend, or third-party integrators.

Best practices

• Keep the generated swagger.ts under a docs or config folder and import it in your main server bootstrap.
• Populate info.title, info.version, and servers to reflect the deployment environments.
• Split large specs: keep components and paths in separate files and reference them from the generated loader.
• Use securitySchemes in components to document auth flows (Bearer, OAuth2) and attach security to relevant paths.
• Validate your OpenAPI spec with a linter (e.g., openapi-validator) after customizing the generated file.

Example use cases

• Create swagger.ts that mounts Swagger UI at /api-docs and serves a bundled OpenAPI JSON.
• Generate a starter OpenAPI 3.x spec with basic info, one example path, and JWT bearer security scheme.
• Produce a TypeScript-friendly loader that reads paths/components from other modules for large APIs.
• Add a swagger setup step to project scaffolding so every new service includes documentation by default.