Introduction

openapi-metadata is a framework agnostic library to automatically generate OpenAPI schemas and documentation by using Typescript decorators and metadata.

users_controller.ts

import { ApiOperation, ApiResponse } from "openapi-metadata/decorators";
import User from "./user";

class UsersController {
  @ApiOperation({
    method: "get",
    pattern: "/users",
    summary: "List users"
  })
  @ApiResponse({ type: [User] })
  async list() {
    ...
  }
}

user.ts

import { ApiProperty } from "openapi-metadata/decorators";

class User {
  @ApiProperty()
  declare id: number;

  @ApiProperty()
  declare name: string;

  @ApiProperty({ required: false })
  declare mobile?: string;
}

index.ts

import "reflect-metadata";
import { generateDocument } from "openapi-metadata";
import UsersController from "./users_controller";

const document = await generateDocument({
  controllers: [UsersController],
  document: {
    info: {
      name: "My Api",
      version: "1.0.0",
    },
  },
});

console.log(document); // <- Your generated OpenAPI specifications

• ✅ Fully compliant OpenAPI V3
• ✅ Automatic type inference
• ✅ Supports Scalar, Swagger UI and Rapidoc
• ✅ Extensible with custom type loaders
• ✅ Ready to be integrated with your favorite framework

Getting started

Setup

Install openapi-metadata and reflect-metadata using your favorite package manager.

npm install openapi-metadata reflect-metadata

Import reflect-metadata in your main file.

index.ts

import "reflect-metadata";

// Rest of your app

Enable experimentalDecorators and experimentalDecorators.

tsconfig.json

{
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true
  }
}

Create your OpenAPI document

To get started, you can use the generateDocument function to create an (almost) empty documentation. You can define a base document that will be merged with the generated one.

index.ts

import "reflect-metadata";
import { generateDocument } from "openapi-metadata";

const builder = await generateDocument({
  controllers: [],
  document: {
    info: {
      name: "My API",
      version: "1.0.0",
    },
  },
});

console.log(document.build()); // <- Your generated OpenAPI specifications

Create your first controller

A controller is a simple class where each methods could be an Operation. In the following example we have a UsersController which declares an operation GET /users that returns a list of Users.

controllers/users_controller.ts

import { ApiOperation, ApiResponse } from "openapi-metadata/decorators";
import User from "../schemas/user";

export default class UsersController {
  @ApiOperation({
    method: "get",
    pattern: "/users",
    summary: "List users",
  })
  @ApiResponse({ type: [User] })
  async list() {
    // ...your logic
  }
}

Create your first schema

In our controller we define the response of your operation to be [User] (a list of users). We now need to create this model.

By using the @ApiProperty decorator on class we can define the properties of our schema.

Unlike other libraries like @nestjs/swagger, every element of your OpenAPI schema is lazy-loaded. Your models will only be part of your documentation if it is used.

schemas/user.ts

import { ApiProperty } from "openapi-metadata/decorators";

export default class User {
  @ApiProperty()
  declare id: string;

  @ApiProperty({ example: "John Doe" })
  declare name: string;

  @ApiProperty()
  declare email: string;

  @ApiProperty({ required: false })
  declare mobile?: string;
}

Add the controller to the generated document

Now that we have our controller ready, we can use it to generate our document.

index.ts

import "reflect-metadata";
import { generateDocument } from "openapi-metadata";
import UsersController from "./controllers/users_controller.ts";

const builder = await generateDocument({
  controllers: [UsersController],
  document: {
    info: {
      name: "My API",
      version: "1.0.0",
    },
  },
});

console.log(document.build()); // <- Your generated OpenAPI specifications

Going further