@dota2classic/nest-openapi-client-generator

Generates OpenAPI specs from NestJS microservices without requiring infrastructure (no DB, Redis, RabbitMQ connections needed).

Uses @nestjs/testing's useMocker() to auto-mock all dependencies.

Installation

yarn add -D @dota2classic/nest-openapi-client-generator

Usage

1. Create a generator script

Create scripts/generate-openapi.js in your microservice:

const { runGenerator } = require("@dota2classic/nest-openapi-client-generator");
const { AppModule } = require("../dist/src/app.module");

runGenerator(AppModule, {
  title: "GameServer API",
  description: "Matches, players, MMRs",
  version: "1.0",
  tags: ["game"],
  bearerAuth: true,
});

2. Add npm script

{
  "scripts": {
    "openapi:generate": "node scripts/generate-openapi.js"
  }
}

3. Run after build

yarn build && yarn openapi:generate ./openapi.json

API

generateOpenApiSpec(appModule, options)

Returns the OpenAPI document as an object.

import { generateOpenApiSpec } from "@dota2classic/nest-openapi-client-generator";

const spec = await generateOpenApiSpec(AppModule, {
  title: "My API",
  description: "Description",
  version: "1.0",
  tags: ["tag1", "tag2"],
  bearerAuth: true,
});

generateOpenApiSpecToFile(appModule, options, outputPath)

Generates and writes the spec to a file.

import { generateOpenApiSpecToFile } from "@dota2classic/nest-openapi-client-generator";

await generateOpenApiSpecToFile(AppModule, options, "./openapi.json");

runGenerator(appModule, options, outputPath?)

CLI helper that handles process exit codes. Use this in your generator script.

import { runGenerator } from "@dota2classic/nest-openapi-client-generator";

// outputPath defaults to process.argv[2] or "./openapi.json"
runGenerator(AppModule, options);

CI/CD Example

# .github/workflows/generate-api-client.yml
name: Generate API Client

on:
  push:
    branches: ["master"]

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20.x

      - run: yarn install
      - run: yarn build
      - run: yarn openapi:generate ./openapi.json

      - uses: actions/upload-artifact@v4
        with:
          name: openapi-spec
          path: openapi.json

How it works

1. Creates a NestJS testing module with your AppModule
2. Uses useMocker(() => ({})) to auto-mock ALL dependencies
3. Initializes the app (without connecting to anything)
4. Extracts OpenAPI spec via SwaggerModule.createDocument()
5. Closes the app and returns the spec

This means your CI doesn't need service containers for Postgres, Redis, RabbitMQ, etc.