@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 [options] [input]

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

Options:
  -o, --output-dir <path>                  Output directory for generated services
  --openapi-types-import-path <path>       Path to schema types file (.d.ts), eg: "../openapi.d.ts"
  -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.
  --operation-generics-import-path <path>  Path to operation generics file (default: "@openapi-qraft/react")
  --file-header <string>                   Header to be added to the generated file (eg: /* eslint-disable */)
  --postfix-services <string>              Postfix to be added to the generated service name (eg: Service)
  --explicit-import-extensions             All import statements will include explicit `.js` extensions. Ideal for projects using ECMAScript modules.
  -h, --help                               display help for command

Example

To generate services from an OpenAPI schema file:

openapi-qraft https://example.com/openapi.json --output-dir src/api --openapi-types-import-path ../openapi.d.ts

This command generates service declarations and React Query hooks types in the src/api directory based on the schema.json file.

Required Options

• -o <path>, --output-dir <path>: Specify where to output the generated services.
  • Example: --output-dir src/api
• --openapi-types-import-path <path>: Set the path to the schema types definition file to ensure consistent type usage (assumed, you already have openapi.d.ts as a result of the openapi-typescript utility).
  • The path is the exact import specifier used in the generated services. It should be _relative to the service output directory.
  • Examples:
    • --openapi-types-import-path ../openapi.d.ts
    • --openapi-types-import-path '@/api/openapi.d.ts'
    • --openapi-types-import-path '@external-package-types'

Useful 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/

Edge-case Options

• --operation-generics-import-path <path>: Define the path to the operation generics file, allowing for custom operation handling (optional, default: @openapi-qraft/react).
• --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.
• --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).
• -h, --help: Display help for the command (optional).

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.