📘 @nodeboot/starter-openapi – Node-Boot OpenAPI Starter

Overview

The @nodeboot/starter-openapi package generates an OpenAPI 3 specification from your Node-Boot controllers and can also serve Swagger UI for interactive API documentation.

It reads Node-Boot route metadata, request parameter metadata, response metadata, model metadata, and class-validator rules to build a spec automatically.

✨ Features

✅ Automatic OpenAPI 3 generation from Node-Boot controllers
✅ Swagger UI integration at /api-docs
✅ Schema generation from models decorated with @Model()
✅ class-validator support for richer schema output
✅ Endpoint customization with @OpenAPI()
✅ Response documentation with @ResponseSchema()
✅ Works with Express, Fastify, Koa, and native HTTP

🚀 Installation

pnpm add @nodeboot/starter-openapi

🔥 Usage

1️⃣ Enable OpenAPI generation

Add @EnableOpenApi() to your application class. This exposes the generated JSON spec at:

• /api-docs/swagger.json

If you also want the Swagger UI, add @EnableSwaggerUI().

import "reflect-metadata";
import {Container} from "typedi";
import {NodeBoot, NodeBootApp, NodeBootApplication, NodeBootAppView} from "@nodeboot/core";
import {ExpressServer} from "@nodeboot/express-server";
import {EnableDI} from "@nodeboot/di";
import {EnableComponentScan} from "@nodeboot/aot";
import {EnableOpenApi, EnableSwaggerUI} from "@nodeboot/starter-openapi";

@EnableDI(Container)
@EnableOpenApi()
@EnableSwaggerUI()
@EnableComponentScan()
@NodeBootApplication()
export class SampleApp implements NodeBootApp {
    start(): Promise<NodeBootAppView> {
        return NodeBoot.run(ExpressServer);
    }
}

@EnableOpenApi() enables spec generation. @EnableSwaggerUI() additionally serves the Swagger UI at /api-docs/ and redirects /docs to /api-docs/.

2️⃣ Document controller endpoints

Use @ResponseSchema() to describe successful responses and @OpenAPI() to override or extend the generated operation. @OpenAPI() can be applied at the controller or method level.

import {Body, Controller, Get, HttpCode, Param, Post, Put} from "@nodeboot/core";
import {OpenAPI, ResponseSchema} from "@nodeboot/starter-openapi";
import {CreateUserDto, UpdateUserDto, UserModel} from "../models";

@Controller("/users", "v1")
export class UserController {
    @Get("/")
    @ResponseSchema(UserModel, {isArray: true, description: "Return a list of users"})
    async getUsers(): Promise<UserModel[]> {
        return [];
    }

    @Get("/:id")
    @OpenAPI({summary: "Get a user by ID"})
    @ResponseSchema(UserModel)
    async getUserById(@Param("id") userId: string): Promise<UserModel> {
        return {} as UserModel;
    }

    @Post("/")
    @HttpCode(201)
    @OpenAPI({summary: "Create a new user"})
    @ResponseSchema(UserModel)
    async createUser(@Body() userData: CreateUserDto): Promise<UserModel> {
        return {} as UserModel;
    }

    @Put("/:id")
    @OpenAPI({summary: "Update a user"})
    @ResponseSchema(UserModel)
    async updateUser(@Param("id") userId: string, @Body() userData: UpdateUserDto): Promise<UserModel> {
        return {} as UserModel;
    }
}

What is inferred automatically:

• paths from @Controller() + HTTP method decorators
• path params from @Param() and route templates like /:id
• query params from query parameter decorators and query DTOs
• request body from @Body() / body parameter metadata
• success status code from response metadata such as @HttpCode(201)
• tags from the controller class name (for example UserController → User)

3️⃣ Document response bodies

@ResponseSchema() accepts either a model class or a primitive type string.

Model response

@Get("/:id")
@ResponseSchema(UserModel)
async getUserById(@Param("id") userId: string): Promise<UserModel> {
    return {} as UserModel;
}

Array response

@Get("/")
@ResponseSchema(UserModel, {isArray: true, description: "Return a list of users"})
async getUsers(): Promise<UserModel[]> {
    return [];
}

Primitive response

import {Controller, Get} from "@nodeboot/core";
import {ResponseSchema} from "@nodeboot/starter-openapi";

@Controller("/hello", "v1")
export class HelloController {
    @Get("/")
    @ResponseSchema("string")
    async hello(): Promise<string> {
        return "Hello, World!";
    }
}

Supported primitive names include string, number, integer, boolean, object, and array.

4️⃣ Define schemas with @Model()

Use @Model() on DTOs and response models that should appear under components.schemas. For response classes, @ResponseSchema() can auto-register the class, but explicitly decorating models with @Model() is the clearest approach.

import {Property} from "@nodeboot/core";
import {IsEmail} from "class-validator";
import {Model} from "@nodeboot/starter-openapi";

@Model()
export class UserModel {
    @Property({description: "User ID"})
    id: number;

    @Property({description: "User email address"})
    @IsEmail()
    email: string;

    @Property({description: "User name"})
    name?: string;
}

5️⃣ Use validation decorators for richer schemas

Validation metadata is converted into OpenAPI schema details through class-validator-jsonschema.

import {IsNotEmpty, IsString, MaxLength, MinLength} from "class-validator";
import {Model} from "@nodeboot/starter-openapi";

@Model()
export class UpdateUserDto {
    @IsString()
    @IsNotEmpty()
    @MinLength(9)
    @MaxLength(32)
    password: string;
}

This is especially useful for request DTOs passed to @Body().

6️⃣ Generic models are supported

The starter can resolve generic model bindings when you provide them to @Model().

import {Page} from "@nodeboot/core";
import {Model} from "@nodeboot/starter-openapi";
import {UserModel} from "./UserModel";

@Model({T: UserModel})
export class UserPage extends Page<UserModel> {}

This pattern is used in the sample MongoDB application for paginated responses.

7️⃣ Configure OpenAPI metadata in app-config.yaml

OpenAPI settings are loaded from the openapi configuration path.

openapi:
    info:
        contact:
            name: "Manuel Santos"
            email: "[email protected]"
            url: "https://www.linkedin.com/in/manuel-brito-dos-santos-a7a20a6b/"
        license:
            name: MIT
            url: "https://github.com/nodejs-boot/node-boot/blob/main/LICENSE"
    servers:
        - url: http://localhost:3000
          description: Localhost server
    externalDocs:
        url: "https://nodeboot.gitbook.io/"
        description: "Node-Boot official documentation"
    securitySchemes:
        basicAuth:
            scheme: "basic"
            type: "http"

Supported config keys are:

• info
• servers
• security
• tags
• externalDocs
• securitySchemes

If present, these values are merged into the generated OpenAPI document. By default, title, version, and description are taken from the application's build info and can be overridden here.

8️⃣ Swagger UI routes

When @EnableSwaggerUI() is enabled, the starter serves:

• GET /api-docs/ → Swagger UI
• GET /api-docs/swagger.json → generated OpenAPI JSON
• GET /docs → redirect to /api-docs/

These routes are built into the starter for all supported server adapters.

🧠 How spec generation works

At startup, the starter:

1. collects Node-Boot controller/action metadata
2. converts controller routes into OpenAPI paths
3. infers parameters and request bodies from method parameter metadata
4. builds schemas from @Model() classes
5. merges in class-validator-derived schemas
6. loads precompiled schemas from dist/node-boot-models.json when available
7. merges openapi config values into the final document

@OpenAPI() metadata is applied last, so it can override generated operation fields such as summary, description, responses, security, and more.

📦 Exports

This package primarily exposes:

• EnableOpenApi
• EnableSwaggerUI
• OpenAPI
• ResponseSchema
• Model

✅ Supported servers

• Express
• Fastify
• Koa
• Native HTTP

📄 License

MIT