playbooks

home / skills / ehtbanton / claudeskillsrepo / swagger-docs-generator

swagger-docs-generator skill

/swagger-docs-generator

This skill generates a complete Swagger UI setup for Express APIs in TypeScript, producing a ready-to-use swagger.ts configuration.

npx playbooks add skill ehtbanton/claudeskillsrepo --skill swagger-docs-generator

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

Files (2)
SKILL.md
679 B
---
name: swagger-docs-generator
description: Generate Swagger/OpenAPI documentation setup for REST APIs. Triggers on "create swagger docs", "generate api documentation", "swagger setup", "openapi docs config".
---

# Swagger Docs Generator

Generate Swagger UI setup and configuration for API documentation.

## Output Requirements

**File Output:** `swagger.ts` with express-swagger-ui configuration
**Format:** Valid TypeScript
**Standards:** OpenAPI 3.x, swagger-ui-express

## When Invoked

Immediately generate Swagger documentation setup.

## Example Invocations

**Prompt:** "Create Swagger docs for Express API"
**Output:** Complete Swagger UI setup with configuration.

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.

FAQ

What file does the skill produce?

It outputs a TypeScript file named swagger.ts configured for swagger-ui-express and OpenAPI 3.x.

Can I serve an external OpenAPI JSON file instead of embedding the spec?

Yes. The generated code can load an external JSON/YAML spec or import separate components and paths for modular specs.