OpenAPI code generation CLI

NOTE: This CLI tool is specifically designed for custom usage within our organization. The generated code output is in alignment with our internal templates.

Use this tool to generate code (Zod schemas, API definitions and React queries) from OpenAPI v3 specification. API definitions are customized to fit the REST client wrapper used in our Next.js template. React queries are generated in alignment with our code standards, without the need for explicit types.

The tool partially leverages code from openapi-zod-client repository.

Setup

yarn add @povio/openapi-codegen-cli

Example

yarn openapi-codegen generate --input http://localhost:3001/docs-json

Options

Generate command (generates Zod schemas, API definitions and React queries)

  --input                             Path/url to OpenAPI/Swagger document as json/yaml
  --output                            Output path (default: 'output')
  --includeNamespaces                 Include namespaces inside generated files (default: true)
  --splitByTags                       Split output into directories based on tags in OpenAPI operations (default: true)
  --defaultTag                        Default tag name for code shared accross multiple tags (default: 'Common')
  --excludeTags                       Comma separated list of tags excluded from the output
  --extractEnums                      Enums are extracted as seperate Zod schemas (default: true)
  --removeOperationPrefixEndingWith   Removes prefix that ends with value from operation names (default: 'Controller_')
  --importPath                        Import path (default: 'ts', possible: 'ts' | 'relative' | 'absolute')
  --prettier                          Run prettier command on output after code generation (default: true)
  --verbose                           Show log messages during execution

Check command (checks if OpenAPI spec is compliant)

  --input                             Path/url to OpenAPI/Swagger document as json/yaml
  --splitByTags                       Split output into directories based on tags in OpenAPI operations (default: true)
  --defaultTag                        Default tag name for code shared accross multiple tags (default: 'Common')
  --excludeTags                       Comma separated list of tags excluded from the output
  --verbose                           Show log messages during execution

Development

Test locally

# prerequisites
corepack install
yarn

# run tests
yarn test

# run sources with tsx
yarn start --help
yarn start generate --input ./test/petstore.yaml --verbose

# build new version
yarn build

# test build
yarn start --help
yarn start:dist generate --input ./test/petstore.yaml --verbose