Skip to content

configuration.md

Latest commit

 

History

History
99 lines (71 loc) · 3.06 KB

configuration.md

File metadata and controls

99 lines (71 loc) · 3.06 KB

Configuration

Basic

The connector reads config.{json,yaml} file in the configuration folder. The file contains information about the schema file path and its specification:

files:
  - file: swagger.json
    spec: openapi2
  - file: openapi.yaml
    spec: openapi3
    trimPrefix: /v1
    envPrefix: PET_STORE
  - file: schema.json
    spec: ndc

The config of each element follows the config schema of ndc-http-schema.

You can add many API documentation files into the same connector.

Important

Conflicted object and scalar types will be ignored. Only the type of the first file is kept in the schema.

Supported specs

OpenAPI

HTTP connector supports both OpenAPI 2 and 3 specifications.

  • oas3/openapi3: OpenAPI 3.0/3.1.
  • oas2/openapi2: OpenAPI 2.0.

HTTP Connector schema

Enum: ndc

HTTP schema is the native configuration schema which other specs will be converted to behind the scene. The schema extends the NDC Specification with HTTP configuration and can be converted from other specs by the NDC HTTP schema CLI.

Timeout and retry

The global timeout and retry strategy can be configured in each file:

files:
  - file: swagger.json
    spec: oas2
    timeout:
      value: 30
    retry:
      times:
        value: 1
      delay:
        # The initial wait time in milliseconds before a retry is attempted.
        # The connector prefers the Retry-After header in the response if exists
        value: 500
      httpStatus: [429, 500, 502, 503]
      
      ## How much does the reconnection time vary relative to the base value. 
      ## This is useful to prevent multiple clients to reconnect at the exact same time, as it makes the wait times distinct.
      ## Must be in range (0, 1); Defaults to 0.5.
      # jitter: 0.5
      
      ## How much should the reconnection time grow on subsequent attempts.
      ## Must be >=1; 1 = constant interval. Defaults to 1.5.
      # multiplier: 1.5

      ## Maximum total time in seconds for all retries.
      # maxElapsedTimeSeconds: 600

      ## How much can the wait time in seconds grow. Defaults to 60 seconds.
      # maxIntervalSeconds: 60

JSON Patch

You can add JSON patches to extend API documentation files. HTTP connector supports merge and json6902 strategies. JSON patches can be applied before or after the conversion from OpenAPI to HTTP schema configuration. It will be useful if you need to extend or fix some fields in the API documentation such as server URL.

files:
  - file: openapi.yaml
    spec: oas3
    patchBefore:
      - path: patch-before.yaml
        strategy: merge
    patchAfter:
      - path: patch-after.yaml
        strategy: json6902

See the example for more context.

Runtime Settings

Stringify JSON (boolean)

This setting treats the arbitrary JSON scalars as a JSON string. This setting is useful for some use cases, for example, making the schema compatible with PromptQL.