SwaggerForge

SwaggerForge is a TypeScript-first library and CLI tool that automatically generates Swagger / OpenAPI documentation for your REST APIs.
It is designed to work on both small and large projects, supporting framework-agnostic core logic, schema inference (Zod, Joi, Class-validator), and Docker-based development.

Features

• Framework-agnostic OpenAPI generator
• CLI tool for generating and serving Swagger documentation
• Docker-ready for easy deployment
• Schema inference from Zod, Joi, Class-validator
• Supports large projects with modular directory structure
• Extensible via plugins
• Swagger UI middleware for Express and Fastify

Project Structure

swaggerforge/ ├── src/ │ ├── core/ # Core OpenAPI generator logic │ │ ├── generator.ts # Builds OpenAPI spec │ │ ├── schema-mapper.ts # Converts schemas (Zod/Joi/DTOs → OpenAPI) │ │ ├── route-parser.ts # Route scanning/parsing logic │ │ ├── config.ts # Handles user configuration │ │ └── types.ts # Shared TypeScript types/interfaces │ │ │ ├── adapters/ # Framework-specific integrations │ │ ├── express.ts │ │ ├── fastify.ts │ │ └── nest.ts │ │ │ ├── cli/ # CLI entry and commands │ │ ├── index.ts │ │ └── commands/ │ │ ├── generate.ts │ │ └── serve.ts │ │ │ ├── middleware/ # Swagger UI middlewares │ │ ├── express-middleware.ts │ │ └── fastify-middleware.ts │ │ │ ├── plugins/ # Extensible plugin system │ │ └── example-plugin.ts │ │ │ └── utils/ # Helper utilities │ ├── file-helpers.ts │ ├── logger.ts │ └── deep-merge.ts │ ├── examples/ # Example apps for testing │ ├── express-app.ts │ ├── nest-app.ts │ └── fastify-app.ts │ ├── tests/ # Unit and integration tests │ ├── core/ │ ├── adapters/ │ └── cli/ │ ├── Dockerfile ├── docker-compose.yml ├── package.json ├── tsconfig.json ├── swaggerforge.config.ts # Optional user config └── README.md

Installation

git clone https://github.com/Princethawani/swaggerforge.git
cd swaggerforge
npm install

CLI Usage

Generate a Swagger spec:

npx ts-node src/cli/index.ts generate <input-folder> <output-file>


Example:

npx ts-node src/cli/index.ts generate ./examples ./swagger.json


Serve Swagger UI:

npx ts-node src/cli/index.ts serve ./swagger.json --port 4000


Show help:

npx ts-node src/cli/index.ts --help

Docker Usage

Build the Docker image:

sudo docker build -t swaggerforge .


Run the CLI inside Docker:

sudo docker run --rm -v $(pwd)/output:/app/output swaggerforge generate ./examples ./output/swagger.json


Swagger spec will be available in ./output/swagger.json.

Development

Run CLI in dev mode:

npm run dev


Build TypeScript project:

npm run build


Run tests:

npx ts-node tests/core/generator.test.ts

Contributing

Fork the repo and create a feature branch

Ensure TypeScript compiles and tests pass

Submit a pull request with a clear description




Running-Project: npx ts-node src/cli/index.ts generate ./my-project/routes ./swagger.
                 npx ts-node src/cli/index.ts generate ./my-project/SWAGGERFORGE/examples ./output/swagger.json


uooing-the-UI: npx ts-node src/cli/index.ts serve ./swagger.json