@openapi-qraft/cli

@openapi-qraft/cli is a powerful command-line utility designed to streamline the development process by generating service declarations and typed React Query interfaces directly from an OpenAPI Schema. With @openapi-qraft/cli, frontend developers can easily generate typed API clients, ensuring type safety and improving development efficiency within React applications.

Features

• Typed React Query Interfaces: Create typed React Query hooks for seamless and type-safe API requests.
• Generate Typed Services: Automatically generate service declarations from an OpenAPI Schema.

Installation

npm install -g @openapi-qraft/cli

Usage

Usage: openapi-qraft --plugin tanstack-query-react --plugin openapi-typescript [input] [options]

Generate TypeScript types from OpenAPI 3.x Document. Based on "openapi-typescript" (https://github.com/drwpow/openapi-typescript/)

Arguments:
  input                                           Input OpenAPI Document file path, URL (json, yml) (default: null)

Options:
  -o, --output-dir <path>                         Output directory for generated services
  -rm, --clean                                    Clean output directory before generating services
  --filter-services <glob-pattern>                Filter services to be generated by glob pattern. Eg: "/user/**,/post/**". See NPM `micromatch` package for more
                                                  details.
  --postfix-services <string>                     Postfix to be added to the generated service name (eg: Service)
  --service-name-base <endpoint[<index>] | tags>  Use OpenAPI Operation `endpoint[<index>]` path part (e.g.: "/0/1/2") or `tags` as the base name of the service.
                                                  (default: "endpoint[0]")
  --file-header <string>                          Header to be added to the generated file (eg: /* eslint-disable */)
  --openapi-types-import-path <path>              Path to schema types file (.d.ts), eg: "../schema.d.ts"
  --explicit-import-extensions                    All import statements will include explicit `.js` extensions. Ideal for projects using ECMAScript modules.
  --export-openapi-types [bool]                   Export the OpenAPI schema types from the generated `./index.ts` file (default: true)
  --operation-generics-import-path <path>         Path to operation generics file (default: "@openapi-qraft/react")
  --openapi-types-file-name <path>                OpenAPI Schema types file name, eg: "schema.d.ts" (default: "schema.ts")
  --enum                                          Export true TS enums instead of unions
  -t, --export-type                               Export top-level `type` instead of `interface`
  --immutable                                     Generate readonly types
  --additional-properties                         Treat schema objects as if `additionalProperties: true` is set
  --empty-objects-unknown                         Generate `unknown` instead of `Record<string, never>` for empty objects
  --default-non-nullable                          Set to `false` to ignore default values when generating non-nullable types
  --properties-required-by-default                Treat schema objects as if `required` is set to all properties by default
  --array-length                                  Generate tuples using array minItems / maxItems
  --path-params-as-types                          Convert paths to template literal types
  --alphabetize                                   Sort object keys alphabetically
  --exclude-deprecated                            Exclude deprecated types
  --no-blob-from-binary                           If this option is enabled, binary format fields will not be converted to Blob types, preserving the native
                                                  representation
  -h, --help                                      display help for command

Usage example

The command below generates Qraft API services for the OpenAPI schema and places them in the src/api directory:

npx openapi-qraft --plugin tanstack-query-react --plugin openapi-typescript https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml \
  --output-dir src/api

Required

• -o <path>, --output-dir <path>: Specify where to output the generated services.
  • Example: --output-dir src/api

Edge-case Options

• -rm, --clean: Clean the specified output directory services before generating to remove stale files (optional).
• --filter-services: Filter services to be generated by glob pattern (optional). See micromatch package for more details.
  • Examples:
    • --filter-services '/user/**,/post/**' - include only API endpoints that start with /user/ or /post/
    • --filter-services '**,!/internal/**' - include all API endpoints except those that start with /internal/
• --service-name-base <endpoint[<index>] | tags>: Use OpenAPI Operation endpoint[<index>] path part (e.g.: /0/1/2) or tags as the base name of the service. (optional, default: endpoint[0]).
  • Examples:
    • --service-name-base endpoint[0] generates services/FooService.ts for the endpoint /foo/bar/baz
    • --service-name-base endpoint[1] generates services/BarService.ts for the endpoint /foo/bar/baz
    • --service-name-base endpoint[3] generates services/BazService.ts for the endpoint /foo/bar/baz (if the endpoint is shorter than the index, the last part is used)
    • --service-name-base tags will generate services based on the OpenAPI Operation tags instead of the endpoint.
      • If multiple tags are present for the operation, similar services will be created for each tag. Operation with tags: [Foo, Bar] will generate services/FooService.ts and services/BarService.ts.
      • If there are no tags for the operation, the services will be created under the default tag. Operation with empty tags: [] will generate services/DefaultService.ts.
• --explicit-import-extensions: Include explicit .js extensions in all import statements. Ideal for projects using ECMAScript modules when TypeScript's --moduleResolution is node16 or nodenext (optional).
• --file-header <string>: Add a custom header to each generated file, useful for disabling linting rules or adding file comments (optional).
  • Example: --file-header '/* eslint-disable */'
• --postfix-services <string>: Customize the generated service names with a specific postfix (optional, default: Service).
  • Example: --postfix-services Endpoint will generate services/UserEndpoint.ts instead of services/UserService.ts.
• --plugin <name_1> --plugin <name_2>: Generator plugins to be used. (choices: tanstack-query-react, openapi-typescript)
  • Examples:
    • --plugin tanstack-query-react --plugin openapi-typescript generates Qraft Services and openapi-typescript types file.
    • --plugin tanstack-query-react generates Qraft Services only.
    • --plugin openapi-typescript generates openapi-typescript types file only.
• -h, --help: Display help for the command (optional).

Plugin System

The following plugins are currently supported:

• openapi-typescript - Generates TypeScript types from an OpenAPI Document. The main difference from the original openapi-typescript package is that format: binary fields default to Blob types instead of remaining as string. This behavior can be altered using the --no-blob-from-binary option.
• tanstack-query-react - Generates Qraft API services for React.

Plugin must be provided with the --plugin <name> option. By default, the tanstack-query-react plugin is used. It is possible to use multiple plugins at the same time. For example, --plugin tanstack-query-react --plugin openapi-typescript generates Qraft API services & schema types file.

--plugin tanstack-query-react options

• --openapi-types-import-path <path>: Set the path to the schema types definition file to ensure consistent type usage (assumed, you already have schema.d.ts as a result of the openapi-typescript utility). You also probably don't need the --plugin openapi-typescript option in this case.
  • The path is the exact import specifier used in the generated services. It should be relative to the service output directory. Optional, if the --plugin openapi-typescript is used. Required otherwise.
    • Examples:
      • --openapi-types-import-path ../openapi.d.ts
      • --openapi-types-import-path '@/api/openapi.d.ts'
      • --openapi-types-import-path '@external-package-types'
• --operation-generics-import-path <path>: Define the path to the operation generics file, allowing for custom operation handling (optional, default: @openapi-qraft/react).
• --export-openapi-types [bool]: Export the OpenAPI schema types from the generated ./index.ts file. (optional, default: true, if --plugin openapi-typescript is used)

--plugin openapi-typescript options

• --openapi-types-file-name <path>: OpenAPI Schema types file name, e.g., schema.d.ts (default: schema.ts).
• --enum: Export true TypeScript enums instead of unions.
• -t, --export-type: Export top-level type instead of interface.
• --immutable: Generate readonly types.
• --additional-properties: Treat schema objects as if additionalProperties: true is set.
• --empty-objects-unknown: Generate unknown instead of Record<string, never> for empty objects.
• --default-non-nullable: Set to false to ignore default values when generating non-nullable types.
• --properties-required-by-default: Treat schema objects as if required is set to all properties by default.
• --array-length: Generate tuples using array minItems / maxItems.
• --path-params-as-types: Convert paths to template literal types.
• --alphabetize: Sort object keys alphabetically.
• --exclude-deprecated: Exclude deprecated types.
• --no-blob-from-binary: If this option is enabled, format: binary fields will not be converted to Blob types, preserving the native type. Could be used with --plugin openapi-typescript option.

In-project Setup

Add the following "scripts" to your package.json file:

{
  "devDependencies": {
    "@openapi-qraft/cli": "latest"
  },
  "scripts": {
    "generate-client": "openapi-qraft --plugin tanstack-query-react --plugin openapi-typescript https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml --output-dir src/api"
    // ...other scripts
  }
}

Contributing

Contributions to @openapi-qraft/cli are welcome! Please feel free to submit issues, pull requests, or suggest features to help improve the utility.

License

This project is licensed under the MIT License.