@ivicevic/npm2-test NPM

`openapi-client-generator`

Consuming a REST API can be needlessly complicated at times, especially when having to manually maintain client code, paths etc. In one of our projects at work we relied on restful-react to generate React components and hooks based on an OpenAPI schema which was really nice. However restful-react can be too sophisticated at times and restrictive which we noticed as our application handles a lot of dynamic data that cannot be easily expressed by generic hooks.

Eventually we ran into the scenario where sometimes we'd really just like to send a simple request without any complex wrappers or hooks, yet have those client methods be automatically generated. Thus this command line tool has been created to simplify maintaining realiable and up to date client code in our frontend.

Overview

The openapi-client-generator will parse an OpenAPI V3 schema file and create concise methods for each operation yielding the following snippet:

export const createTodoItem = async (
  parameters: {
    listId: string;
  },
  requestBody: TodoItemDto,
  config?: AxiosRequestConfig,
) =>
  axios.post<TodoItemDto>(
    `/api/lists/${parameters.listId}/items`,
    requestBody,
    config,
  );

⚠️ Versions prior to v1 don't generate the respective types for all schemas defined in the spec! Since we're transitioning iteratively in our project the tool reuses the types generated by restful-react. Please read more on that in the usage sections and the feature roadmap section.

Installation

We suggest installing the tool locally into your project by issuing the following command using yarn

yarn add @ivicevic/openapi-client-generator -D

or the following if you use npm

npm i @ivicevic/openapi-client-generator --save-dev

CLI usage

The CLI command usage looks as follows:

openapi-client-generator --input [INPUT] --output [OUTPUT] --types [TYPES]

In our project we run the CLI with the following command:

openapi-client-generator -i ./submodules/schema/v2.yaml -o ./src/api/requests.ts -t ./types.ts

To display more detailed log outputs you can append the --verbose or --debug flags to any command to debug any issues.

For more help run the command openapi-client-generator --help to show a list of all available arguments.

About the `types` argument

The initial versions prior to the release of v1 of the client generator only support parsing and generating the respective operations. No types for schemas are generated (yet) and thus we rely on them being available beforehand. Before this feature gets fully implemented into the CLI we are using the output of restful-react (in combination with its --skipReact command line argument). The generated types are referenced by our generated requests file for the time being. We highly suggest you do the same should you decide to use openapi-client-generator before its v1 release.

API usage

This package is intended to be used as a CLI and it is discouraged to use it via its API as its public methods haven't been properly exposed. If you really want to walk down that dark path nonetheless refer to the src/cli/cli.ts file until we establish a stable API.

Feature roadmap

Major: Generation of types for schemas in the OpenAPI spec
Major: More reliable code generation via typescript and/or ts-morph itself rather than using Handlebars
Minor: Handling nullable and required parameters and objects correctly
Minor: Resolving array types that include either items.allOf, items.oneOf or items.enum

Contribution

All contributions are welcome, be it documentation, bug reports and issues or code contributions.

Since we don't fully support all features of the OpenAPI spec it is really helpful if you report any issues with the respective spec files that cause unexpected behavior so that we can fix them.

To contribute to the code clone the repository, use the Node version denoted in the .nvmrc file (most likely by running nvm use), install its dependencies using yarn install (we are using Yarn 2) and use the following commands as necessary:

Handlebars template files are compiled using either
- yarn build:templates
- yarn watch:templates
The library and CLI are compiled using either
- yarn build:main
- yarn watch:build
Tests are written using Jest and can be executed via either
- yarn test
- yarn test:coverage
Test your code using yarn lint and keep PRs small and concise and follow the conventional commits so that the changelog can be update automatically