Documentation

Documenation

The Documenation module provide helpers in the form of Decorators to document the API. Currently supporting OpenAPI 3.0.0.

Decorators

Documentation for Data classes as Schemas in Open API

• @Documentation.addSchema - Adds a schema to the OpenAPI document.
• @Documenation.addField - Adds a field to the schema.
• @Documentation.getRef - Add a reference to a schema. Causes to generate reference to the schema in the OpenAPI document with $ref syntax.

@Documentation.addSchema({ type: "object" })
export class Address extends BaseEntity {
  @Documentation.addField({ type: "number" })
  id!: number;

  @Documentation.addField({ type: "string" })
  line1!: string;

  @Documentation.addField({ type: "string" })
  line2!: string;

  @Documentation.addField({ type: "string" })
  city!: string;

  @Documentation.addField({ type: "string" })
  state!: string;
}

Documentation for Controllers

• @Documentation.addRoute - Adds a route to the OpenAPI document.

Here is an example for

@Documentation.addRoute({
        description: "Create a new entity",
        tags: ['Address'],
        method: Methods.POST,
        path: `/address`,
        requestBody: {
          $ref: Documentation.getRef(Address),
        },
        responses: {
          "201": {
            description: "Created",
            value: {
              anyOf: [{ type: "string", format: "uuid" }, { type: "integer" }],
            },
          },
          "400": {
            description: "Bad Request",
            value: { $ref: Documentation.getRef(Address) },
          },
        },
      })

Methods exposed

• Documentation.addTags - Adds tags to the OpenAPI Documentation for the controller.
• DocumenaddServers - Adds API Base route to the OpenAPI Documentation.
• Documentation.addInfo - Adds info to the OpenAPI Documentation.

To load the documenation swagger UI express can be used. Here is an example of how to use it:

app
  .getApp()
  .use(
    "/docs",
    swaggerUiExpress.serveWithOptions({ cacheControl: true, maxAge: 64800 })
  );
app.getApp().get("/docs", swaggerUiExpress.setup(Documentation.getAPIJson()));

Note: Security is not yet implemented.