Configure SDK generation

Minimal configuration#

{
  "name": "Acme API",
  "environments": {
    "production": "https://api.acme.com"
  },
  "environmentOrder": ["production"],
  "targets": {
    "typescript": { "packageName": "@acme/api" },
    "python": { "packageName": "acme_api", "projectName": "acme-api" },
    "cli": { "binaryName": "acme" }
  },
  "resources": {}
}

Required properties#

• name — The human-readable SDK or product name.
• resources — The generated client and resource tree.
• targets — Per-language packaging, publishing, and emitter options.
• environments — Named base URLs the client can switch between.
• environmentOrder — The insertion order and default environment.

Targets and resources#

Add a key under targets for each artifact you want to generate. Supported keys include typescript, python, cli, go, rust, java, kotlin, swift, ruby, php, csharp, cpp, and dart.

Set skip: true to keep a target's configuration without generating it. Set promotion: "manual" to hold a build at staging until you promote it.

The resources object defines methods, models, nested resources, request defaults, and per-target visibility. Use skip to omit a method, model, or resource; use only to restrict it to selected targets.

Client settings#

Use clientSettings for constructor options, authentication values, default headers, environment variable names, timeouts, retries, and response headers.

{
  "clientSettings": {
    "defaultTimeout": 30000,
    "defaultRetries": {
      "maxRetries": 2,
      "initialDelaySeconds": 1,
      "maxDelaySeconds": 10
    }
  }
}

Environments and pagination#

environments maps names to base URLs. The first name in environmentOrder is the default.

Define reusable schemes in pagination, then bind one to a method with paginated. Supported types include cursor, cursorId, cursorUrl, offset, pageNumber, and fakePage.

Serialization and OpenAPI overrides#

Use querySettings and multipartSettings to control array and nested-object serialization. Use openapi for SDK-specific code samples, security schemes, and operation-security behavior.

Diagnostics#

Every build analyzes the OpenAPI document and configuration. Use diagnostics to decide which findings fail the build.

{
  "diagnostics": {
    "failOn": "error",
    "maxWarnings": 20,
    "rules": {
      "Endpoint/NotConfigured": "warn"
    }
  }
}

Next steps#