OpenAPI API Client Generation and Compilation

Generate an API client from an OpenAPI schema in YAML format and create a rtk-query api client. This package streamlines this process and ensures a smooth workflow.

Dependencies

1. Node.js and npm: Ensure you have Node.js and npm installed on your system. You can download them from nodejs.org.

Installation

  npm install @layer5/rtk-query-codegen

Usage

Run the script using the following command:

rtk-query-codegen -i /path/to/schema.yml -o /path/to/generated-api.js -c /path/to/codegen-config.json

Config File Options

Simple usage

 {
  apiFile: string
  schemaFile: string
  apiImport?: string
  exportName?: string
  argSuffix?: string
  responseSuffix?: string
  hooks?:
    | boolean
    | { queries: boolean; lazyQueries: boolean; mutations: boolean }
  tag?: boolean
  outputFile: string
  filterEndpoints?:
    | string
    | RegExp
    | EndpointMatcherFunction
    | Array<string | RegExp | EndpointMatcherFunction>
  endpointOverrides?: EndpointOverrides[]
  flattenArg?: boolean
}

Filtering endpoints

If you only want to include a few endpoints, you can use the filterEndpoints config option to filter your endpoints.

 {
  // ...
  // should only have endpoints loginUser, placeOrder, getOrderById, deleteOrder
  filterEndpoints: ['loginUser', /Order/],
}

Endpoint overrides

If an endpoint is generated as a mutation instead of a query or the other way round, you can override that.

{
  // ...
  "endpointOverrides": [
    {
      "pattern": "loginUser",
      "type": "mutation"
    }
  ]
}

Generating hooks

Setting hooks: true will generate useQuery and useMutation hook exports. If you also want useLazyQuery hooks generated or more granular control, you can also pass an object in the shape of: { queries: boolean; lazyQueries: boolean; mutations: boolean }.

Multiple output files

  schemaFile: 'https://petstore3.swagger.io/api/v3/openapi.json',
  apiFile: './src/store/emptyApi.ts',
  outputFiles: {
    './src/store/user.ts': {
      filterEndpoints: [/user/i],
    },
    './src/store/order.ts': {
      filterEndpoints: [/order/i],
    },
    './src/store/pet.ts': {
      filterEndpoints: [/pet/i],
    },
  },
}

The Api.js file

The api.js file contains the generated api endpoints , it injects them into the base rtk client . And then exports all the hooks to use them . If we need to override an api endpoint we can injectEnpoints in a separate file .

Troubleshooting

• If any of the steps fail, the script will exit with a non-zero status code, indicating a failure. Review the error messages to diagnose and resolve any issues.

• Ensure that the Bash script is executable by running chmod +x generate-api.sh.

Important Notes

• Make sure the OpenAPI schema (schema.yml) is updated with latest changes and doesnt contain any breaking changes .

• Always validate and test the generated API client to ensure it functions as expected.

Join the Layer5 community!

Our projects are community-built and welcome collaboration. 👍 Be sure to see the Layer5 Community Welcome Guide for a tour of resources available to you and jump into our Slack!

Find out more on the Layer5 community.