oas-typescript-express

oas-typescript-express is a generator for OpenAPI Specification 3 to express. This tool is powered by openapi-zod-client for the OAS parsing.

Installation

It is recommended to install this as a project dependency so that it can be used in CI consistently.

1# With npm.
2npm install --save-dev @oas-typescript/express
3
4# With yarn.
5yarn add -D @oas-typescript/express

CLI guide

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

Generating server stubs

To generate the server stubs, do this command:

1npx oas-typescript-express generate ./api.json --output generated
2
3# Or, using yarn:
4yarn oas-typescript-express generate ./api.json --output generated
5
6# Or, inside the `scripts` in package.json.
7oas-typescript-express generate ./api.json --output generated

The command above will read the Open API Specification api.json and output them to the generated folder. The result will be as the following.

generated
├── controllers
│   ├── PetController.ts
│   ├── StoreController.ts
│   └── UserController.ts
├── static
│   ├── checksum.json
│   ├── client.ts
│   ├── controller-types
│   │   ├── PetControllerTypes.ts
│   │   ├── StoreControllerTypes.ts
│   │   └── UserControllerTypes.ts
│   ├── security-schemes.ts
│   ├── router.ts
│   ├── types.ts
│   └── utils.ts
└── middleware-helpers.ts

All files are stubs, except the ones in controllers folder and middleware-helpers.ts, where you will need to insert your own logic. The latter is mostly used for validating authorization from the incoming request.

More information

For further documentation, please visit the documentation: https://imballinst.github.io/oas-typescript/docs/nodejs-server-stubs/adapters/express.