Skip to main content
Version: 2.x

Redocly Config Support

Qraft CLI can use a Redocly configuration file (redocly.yaml) to generate one or multiple API clients with custom settings and authentication rules. By integrating with Redocly's powerful configuration schema resolution, you can streamline client generation across various services defined in your project.

Introduction​

Qraft CLI integrates with Redocly's configuration framework to simplify API client generation. This integration allows you to:

Configuration Example: Redocly 🤝 Qraft​

Here's a basic example of a redocly.yaml configuration file:

apis:
  # Main API configuration
  main:
    root: ./openapi.json  # Path to OpenAPI schema
    # Qraft's specific configuration
    x-openapi-qraft:
      output-dir: src/api  # Output directory for a generated API client
      clean: true          # Clean output directory before generation
      plugin:
        tanstack-query-react: true  # Generate React Query hooks
        openapi-typescript: true    # Generate TypeScript types

  # Legacy API configuration
  legacy:
    root: ./legacy-openapi.json
    x-openapi-qraft:
      output-dir: src/legacy-api
      clean: true
      plugin:
        tanstack-query-react: true
        openapi-typescript: true
      # Filter services to only include user-related endpoints
      filter-services:
        - '/users/**'

Generating from Redocly Configuration​

Using the configuration example above, you can generate API clients for both the main and legacy APIs with a single command:

npx @openapi-qraft/cli --redocly

This command will:

  1. Read the redocly.yaml configuration
  2. Generate each API client specified in the configuration

If your configuration file is located elsewhere, you can specify its path:

npx @openapi-qraft/cli --redocly ./path/to/redocly.yaml

Generating Specific APIs​

You can also generate clients for specific APIs by listing their names:

npx @openapi-qraft/cli legacy --redocly

This is particularly useful when you want to generate only certain APIs from your configuration.

Authentication Configuration​

When working with private APIs that require authentication, you can configure authentication headers in your redocly.yaml file. This is particularly useful when your OpenAPI schemas are hosted on private servers or require API keys.

Here's an example of how to configure authentication:

resolve:
  http:
    headers:
      - matches: https://api.example.com/v2/**
        name: X-API-KEY
        envVariable: API_KEY
      - matches: https://example.com/*/test.yaml
        name: Authorization
        envVariable: AUTH_TOKEN

The CLI will automatically use these credentials when fetching the OpenAPI schemas.

Extended Configuration Example​

Here's a more comprehensive example of a redocly.yaml configuration that demonstrates advanced features:

# Enforce unique operationIds across all operations
rules:
  operation-operationId-unique:
    severity: 'error'

apis:
  main:
    root: ../test-fixtures/openapi.json
    x-openapi-qraft:
      plugin:
        tanstack-query-react: true
        openapi-typescript: true
      output-dir: src/tests/fixtures/api
      clean: true
      # Force .js/.ts extensions in imports (useful for ESM)
      explicit-import-extensions: true
      # Custom name for a generated types file
      openapi-types-file-name: openapi.ts
      # Filter which services to generate
      filter-services:
        - '/approval_policies/**'  # Include all approval policies
        - '/entities/**'           # Include all entities
        - '/files/**'             # Include all files
        - '!/internal/**'         # Exclude internal endpoints
      # Set default headers for specific endpoints
      operation-predefined-parameters:
        '/approval_policies/{approval_policy_id}/**': 'header.x-monite-entity-id'
        '/entities/{entity_id}/documents': 'header.x-monite-version'
      # Transform operation names using regex
      operation-name-modifier:
        - '/files/list:[a-zA-Z]+List ==> findAll'  # Rename all *List operations to findAll

Generating Multiple API Client Functions​

Qraft allows you to generate multiple create API client functions with different parameters using the --create-api-client-fn option. This is particularly useful when you need to create specialized clients for different environments or use cases. For more information on using options, please explore the CLI documentation.

Here's an example of how to configure multiple create API client functions:

apis:
  files:
    root: ./openapi.json
    x-openapi-qraft:
      plugin:
        tanstack-query-react: true
        openapi-typescript: true
      output-dir: src/api
      # Generate multiple API client functions with different parameters
      create-api-client-fn:
        # Node.js API client with all services and callbacks
        createInternalNodeAPIClient:
          filename: create-internal-api-client  # Custom filename for the generated function
          services: all                         # Include all services
          callbacks: all                        # Include all callbacks

        # React API client with specific callbacks only
        createReactAPIClient:
          services: none                        # Don't include any services directly
          callbacks:                            # Include only specific callbacks
            - setQueryData
            - getQueryData
            - getQueryKey
            - getInfiniteQueryKey