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 { ,  } from "openapi-metadata/decorators";
import  from "./user";

class  {
  @({
    : ["get"],
    : "/users",
    : "List users"
  })
  @({ : [] })
  async () {
    ...
  }
}

user.ts

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

class  {
  @()
  declare : number;

  @()
  declare : string;

  @({ : false })
  declare ?: string;
}

index.ts

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

const  = await ({
  : [],
  : {
    : {
      : "My Api",
      : "1.0.0",
    },
  },
});

.(); // <- 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 emitDecoratorMetadata 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 {  } from "openapi-metadata";

const  = await ({
  : [],
  : {
    : {
      : "My API",
      : "1.0.0",
    },
  },
});

.(); // <- 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 { ,  } from "openapi-metadata/decorators";
import  from "../schemas/user";

export default class  {
  @({
    : ["get"],
    : "/users",
    : "List users",
  })
  @({ : [] })
  async () {
    // ...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 {  } from "openapi-metadata/decorators";

export default class  {
  @()
  declare : string;

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

  @()
  declare : string;

  @({ : false })
  declare ?: string;
}

Register your controller

Now that we have our controller ready, we can include it when generating our document.

index.ts

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

const  = await ({
  : [],
  : {
    : {
      : "My API",
      : "1.0.0",
    },
  },
});

.(); // <- Your generated OpenAPI specifications