@oas-typescript/express

This section contains the quick start on how to use @oas-typescript/express.

Requirements

The requirements to use @oas-typescript/express are as the following.

• Node.js installation, along with Working package manager, such as npm or yarn.
• OpenAPI 3.0 specification file. If you are still using Swagger 2.0, you might need to migrate or convert your Swagger 2.0 specification into OpenAPI 3.0.

Installation

To install @oas-typescript/express, run the command below.

npm

npm install -D @oas-typescript/express

Yarn

yarn add -D @oas-typescript/express

Usage

To use the CLI, use the following command.

npm

npx oas-typescript-express generate ./path/to/openapi.json --output ./path-to-output-directory

Yarn

yarn oas-typescript-express generate ./path/to/openapi.json --output ./path-to-output-directory

The CLI has following options that can be passed as arguments.

Option	Description	Default value
--output, -o	The output directory.	(pwd)/oas-typescript
--app-security-schemes-field	The security scheme field used in the OpenAPI Specification. Mostly useful when you have custom securitySchemes that are not supported by the specification.	securitySchemes
--app-security-requirements-field	The custom security requirements field used in the OpenAPI Specification. Mostly useful when you have custom security that are not supported by the specification.	security
--module	The output module. Available values are cjs or esm.	esm

There's that! After running that command, you will have your generated files ready at the output directory.

Create a server file

The CLI does not automatically generate a server file, so you will need you create it yourselves. You could create a file, say, server.ts outside of the output folder.

import express from 'express';
import { generatedRouter } from './static/router.js';

const app = express();

app.use(generatedRouter);

app.get('/healthz', (_req, res) => {
  res.send({ healthy: true });
});

app.listen(3000, () => {
  console.info('Server is running on port 3000');
});

So, what we are doing above is, we define the Express application, in which we use the generatedRouter as well as the common router (in the case above we are defining /healthz endpoint which is used to indicate if the server is already running).