openapi-helpers
This package contains scripts, types and functions to help you work with OpenAPI.
Installation
Run the following commands:
npm install --save-dev @map-colonies/openapi-helpers supertest prettier openapi-typescript @types/express
CLI Usage
The package provides a unified CLI for generating TypeScript types and error classes from OpenAPI specifications. All code generation is now performed using the generate
command, which supports subcommands for types and errors.
CLI Arguments Reference
Positional Arguments:
For both generate types
and generate errors
commands, the positional arguments are:
<openapi-file>
: Path to the OpenAPI YAML or JSON file to use as the source schema.<output-file>
: Path to the file where the generated code will be written.
These arguments are required and must be provided in the order shown.
Optional Arguments:
For generate types
:
-f, --format
: Format the generated types using Prettier-t, --add-typed-request-handler
: Add the TypedRequestHandler type to the generated types
For generate errors
:
-f, --format
: Format the generated code using Prettier-e, --errors-output <all|map|classes>
: Specify what to generate (default: all)all
: generate both error classes and error code mappingmap
: generate only the error code mappingclasses
: generate only the error classes
Generate Types
Generate TypeScript types from an OpenAPI schema:
npx @map-colonies/openapi-helpers generate types <openapi-file> <output-file> [options]
For example:
npx @map-colonies/openapi-helpers generate types ./openapi3.yaml ./src/openapi.d.ts --format --add-typed-request-handler
Options:
-f, --format
- Format the generated types usingprettier
.-t, --add-typed-request-handler
- Add theTypedRequestHandler
type to the generated types.
Generate Errors
Generate error classes and error code mappings from an OpenAPI schema:
npx @map-colonies/openapi-helpers generate errors <openapi-file> <output-file> [options]
For example:
npx @map-colonies/openapi-helpers generate errors ./openapi3.yaml ./src/errors.ts --format
Options:
-f, --format
- Format the generated code usingprettier
.-e, --errors-output <all|map|classes>
- Specify what to generate:all
(default): generate both error classes and error code mappingmap
: generate only the error code mappingclasses
: generate only the error classes
Help and Examples
To see all available commands and options:
npx @map-colonies/openapi-helpers --help
npx @map-colonies/openapi-helpers generate --help
npx @map-colonies/openapi-helpers generate types --help
npx @map-colonies/openapi-helpers generate errors --help
Example: Run all generations
You can run both types and errors generation in sequence:
npx @map-colonies/openapi-helpers generate types ./openapi3.yaml ./src/openapi.d.ts --format --add-typed-request-handler
npx @map-colonies/openapi-helpers generate errors ./openapi3.yaml ./src/errors.ts --format --errors-output all
Programmatic Support
[!NOTE] Programmatic usage of the CLI (importing and using the generators directly) is only supported in ECMAScript modules (ESM). CommonJS is not supported for direct imports.
The code generators (generateTypes.mts
and generateErrors.mts
) now support functional programming patterns. You can inject custom transformation logic or AST manipulation by providing functional arguments, making the generators more flexible and composable for advanced use cases.
API Usage
You can import and use the generators directly in your own scripts for full functional programming flexibility:
import { generateTypes, generateErrors } from '@map-colonies/openapi-helpers/generators';
// Generate types
await generateTypes(
'openapi3.yaml',
'src/openapi.d.ts',
{
shouldFormat: true,
addTypedRequestHandler: true,
// inject?: string,
// transform?: (schemaObject, metadata) => ...
}
);
// Generate errors
await generateErrors(
'openapi3.yaml',
'src/errors.ts',
{
shouldFormat: true,
includeMapping: true,
includeErrorClasses: true
}
);
You can pass custom inject
or transform
functions to generateTypes
for advanced AST/code manipulation, enabling highly composable and functional workflows.
TypedRequestHandler
The package contains a wrapper for the express
types package that provides autocomplete for all the request handlers to the API based on the OpenAPI schema. The TypedRequestHandler is initialized with the types generated by openapi-typescript
, and is configured based on operation name or method and path.
Usage
import { TypedRequestHandlers } from '@map-colonies/openapi-helpers/typedRequestHandler';
import type { paths, operations } from './src/openapi.d.ts';
// Initialize the TypedRequestHandlers with the paths and operations types
// This can be done in a separate file and exported, in the same file or even in the same line
type MyHandlers = TypedRequestHandlers<paths, operations>;
export class Controller {
// Define the handler for the operation based on method and path
public getResource: MyHandlers['GET /resource'] = (req, res) => {
res.status(httpStatus.OK).json({id: 1, description: 'description', name: 'name'});
};
// Define the handler for the operation based on the operation name
public getResource: MyHandlers['getResource'] = (req, res) => {
res.status(httpStatus.OK).json({id: 1, description: 'description', name: 'name'});
};
}
RequestSender
The package contains a wrapper for the supertest
package that provides autocomplete for all the requests to the API based on the OpenAPI schema. The RequestSender is initialized with the server's base URL and the OpenAPI schema and the types exported by openapi-typescript
.
import { RequestSender } from '@map-colonies/openapi-helpers/requestSender';
import type { paths, operations } from './src/openapi.d.ts';
const requestSender = await createRequestSender<paths, operations>('path/to/openapi3.yaml', expressApp);
The requestSender object contains all the paths and operations defined in the OpenAPI schema. For example, to send a request to the getUsers
operation with the /users
path and with the GET
method, you can use the following code:
const response = await requestSender.getUsers();
// or
const response = await requestSender.sendRequest({
method: 'get',
path: '/simple-request'
});
The package supports all the operations defined in the OpenAPI schema, either by operation name, or by using the sendRequest
function with the method, path and parameters.
[!IMPORTANT] For the package to function properly, you need to make sure that the following values are configured in your
tsconfig.json
orjsconfig.json
files under compilerOptions:
- module: "NodeNext"
- moduleResolution: "NodeNext"
This page was generated from a remote source. you can find it on https://github.com/MapColonies/openapi-helpers/blob/master/README.md