apigenie-generator client fetch

Tier 1 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification

Generate a TypeScript client for the Fetch API from an OpenAPI document.

Usage

apigenie-generator client fetch [...OPTIONS] INPUT_FILE

Description

The generator writes TypeScript sources with no runtime dependencies: requests go through the global fetch() (or one you pass), so the client runs in browsers and in Node.js 18 or later. The input is an OpenAPI 3.0, 3.1 or 3.2 document or, since 0.12.0, a Swagger 2.0 document (see Swagger 2.0 input).

File Contents
src/types.ts a type per component schema, the ...Params interface of each operation, and the named types of inline bodies
src/operations.ts an async function per operation, and a function per streamed response format
src/metadata.ts DEFAULT_BASE_URL, the AuthCredentials interface and SECURITY_SCHEMES
src/runtime.ts configure(), ApiError, parameter serialization, authentication, body encoding
src/index.ts exports the types, the operations and the public part of the runtime
package.json, tsconfig.json an ES module package built with tsc into dist/ (layout: package only)

With layout: sources, the five files are written directly to the output directory, to be compiled as part of your own project. A client of a shipping API, generated with layout: sources into api/:

import { configure, ApiError, listShipments, getShipment, downloadLabelFile } from "./api/index.js";

configure({
  baseUrl: "https://eu.api.carpetexpress.example/v2",
  auth: {
    apiKey: "ce_live_123", // sent in the X-Api-Key header
    oauth2: () => fetchAccessToken(), // called before every request that needs it
  },
});

try {
  const page = await listShipments({ status: ["in_transit", "delivered"], limit: 20 });
  const shipment = await getShipment(
    { shipmentId: "shp_01J9Z", expand: ["labels"] },
    { signal: AbortSignal.timeout(5000), headers: { "X-Request-Id": "req-1" } },
  );
  const label: Blob = await downloadLabelFile({ labelId: "lbl_1", extension: "pdf" });
} catch (error) {
  if (error instanceof ApiError) {
    console.error(error.status, error.body); // status 0: no response was received
  }
}

Configuration at run time

configure(settings) sets the client-wide settings; settings it doesn’t give keep their values. Every operation function also takes an optional last argument, RequestOptions, with the same settings for that call only, and an AbortSignal.

Setting Meaning
baseUrl Base URL of the API. Defaults to DEFAULT_BASE_URL: the URL of the document’s first server when it is absolute and has no variables, otherwise empty. A call without a base URL throws an ApiError, unless the operation has an absolute server of its own (see Servers).
fetch The fetch() implementation; the global one by default.
headers Headers sent with every request.
auth Credentials, by security scheme name (AuthCredentials).
operationServers Since 0.12.0. Whether an operation with servers of its own is sent to the first of them; true by default. With false, every request goes to baseUrl, for example to a mock server.
signal RequestOptions only: aborts the request.

Operations

Every operation is an exported async function named after its operationId in camel case (list_shipments becomes listShipments), or after its method and path when it has none (GET /pets/{id} becomes getPetsId); see action_naming. The summary and the description become its JSDoc comment, and deprecated operations are marked @deprecated.

export async function getShipment(params: GetShipmentParams, options?: RequestOptions): Promise<Shipment>
export async function listShipments(params: ListShipmentsParams = {}, options?: RequestOptions): Promise<ShipmentPage>
export async function getAccount(options?: RequestOptions): Promise<Account>
  • Parameters of all locations (path, query, header, cookie) are properties of one ...Params object, under their names in the document (params["If-Match"]). A name used in two locations gets the location as a prefix for the second one (queryId). Accept, Content-Type and Authorization header parameters are left out. When no parameter is required, the object defaults to {}.

  • Serialization follows each parameter’s style and explode: simple, label and matrix path parameters; form, spaceDelimited, pipeDelimited and deepObject query parameters. Values that are undefined or null are not sent; Date values are sent in ISO 8601 form. Since 0.12.0, a parameter described by content in a JSON media type instead of a schema is sent as its JSON text, URL-encoded in a query (near=%7B%22type%22%3A%22Point%22...) or a path.

  • The request body is the body property of the params (requestBody when a parameter is already named body). An operation with several request media types gets one: JSON first, then application/x-www-form-urlencoded, multipart/form-data, text/*, and other types. JSON bodies are typed by their schema and sent with JSON.stringify; form bodies are objects (or URLSearchParams), multipart bodies FormData, text bodies string, and other media types Blob. Since 0.12.0, an operation with several request media types of the preferred one’s kind (two JSON types, for example) can send any of them. The params get a contentType property (bodyContentType when a parameter has that name): a union of those media types that defaults to the preferred one. A JSON or form body is typed as the union of their schemas’ types, and the type check doesn’t tie the body to the media type. Media ranges such as image/* are not offered. Multipart bodies are always sent as multipart/form-data, the type fetch gives a FormData body.

    await updateShipment({
      shipmentId,
      "If-Match": etag,
      body: [{ op: "remove", path: "/metadata" }],
      contentType: "application/json-patch+json",
    });
  • Servers. Since 0.12.0, an operation with servers of its own, or whose path item has them, is sent to the first of them, unless it is the document’s first server. Each server variable takes its default value. An absolute server URL is used in place of baseUrl, even when baseUrl is configured. A relative one is resolved against baseUrl as a URL reference, so one starting with / replaces the path of baseUrl. In a browser, a relative baseUrl is itself resolved against the page’s address. Without a baseUrl, or with a relative baseUrl outside a browser, the call fails with an ApiError. operationServers: false sends every request to baseUrl.

  • Left-out operations. Since 0.12.0, an operation marked x-internal: true, or whose path item is, is left out unless internal_operations is true. One marked x-apigenie.codegen.disabled: true is always left out.

  • The result is the body of the success response (2XX, or default when no success response is documented): its schema’s type for JSON, string for text/*, Blob for other media types. Several success responses give a union (Promise<Shipment | Job>), and a response without content adds undefined; an operation whose responses have no content returns Promise<void>. The Accept header is set from the media type of the response.

  • Streams. Since 0.12.0, an operation with a success response in text/event-stream or JSON Lines (application/jsonl, application/x-ndjson, application/x-jsonlines) also gets a function per format. It is named after the operation with EventStream or Jsonl appended, with a number when that name is taken. It takes the same arguments and returns an AsyncIterable of the items typed by itemSchema (x-itemSchema in OpenAPI 3.0 and 3.1 documents). JSON Lines yield one parsed value per non-blank line; a line that isn’t JSON throws an ApiError whose body is the line. Server-sent events yield an object with the event’s data, event, id and retry fields, a ServerSentEvent when no itemSchema describes them. data is the text of its data: lines joined by line feeds, not parsed, and events without data are skipped. The request is sent when the iteration starts, and leaving the loop early closes the connection. The operation’s own function keeps reading its preferred media type as a whole.

    for await (const event of getTrackingEventsJsonl({ shipmentId: "shp_01J9Z" })) {
      console.log(event.status); // a TrackingEvent
    }
  • Security is the operation’s requirements, or the document’s when the operation declares none. Before the request is sent, the first alternative whose credentials are all configured is applied; when none is, the request goes out without credentials.

Types

Component schemas become exported interfaces (plain objects) or type aliases, named in Pascal case (user_profile becomes UserProfile, x-apigenie.codegen.name overrides the name):

Schema TypeScript
object with properties interface; optional properties are marked ?, deprecated ones @deprecated
additionalProperties Record<string, T>, or an index signature next to properties; false without patternProperties: no index signature, or Record<string, never> without properties
patternProperties with additionalProperties: false or a schema object: the union of the pattern schemas’ types (and T) in the Record or the index signature, since 0.12.0; ignored without additionalProperties or with true
enum, const union of literals ("available" | "sold", 1 | 2 | 3)
oneOf, anyOf union (Circle | Square)
allOf intersection (Shape & { name?: string })
prefixItems tuple ([number, number])
type: [T, "null"], OpenAPI 3.0 nullable: true T | null
format: binary string Blob
other strings, date-time included string
integer, number number
{} unknown

Recursive schemas refer to themselves (children?: Tree[]). The client doesn’t validate values against their schemas: constraints such as minimum, pattern or if/then/else generate no code.

Authentication

AuthCredentials has an optional property per security scheme of the document. A credential is a string, or a function returning a string or a promise of one, called before every request that needs it (to refresh tokens).

Scheme Sent as
apiKey the header, query parameter or cookie the scheme names
http with scheme: basic Authorization: Basic ..., the credential being user:password
http with scheme: bearer Authorization: Bearer <credential>
other http schemes Authorization: <scheme> <credential>
oauth2, openIdConnect Authorization: Bearer <credential>

The client implements no OAuth 2.0 flow: it sends the access token you supply.

Errors

Every failure is an ApiError (a subclass of Error) with:

Property Value
status the HTTP status, or 0 when no response was received
body the response body: parsed JSON for JSON media types, otherwise text, undefined when empty
response the Response, when there was one
cause the underlying error, e.g. a network error or a SyntaxError of invalid JSON

A response with a status outside 200-299 throws, as does a success response whose JSON can’t be parsed. So do a network failure, a missing path parameter, and a missing base URL for an operation without an absolute server of its own. A stream function throws them from the first iteration.

Extensions

Extension Effect
x-apigenie.codegen.name name of the type of a component schema
x-apigenie.codegen.action-name name of the function of an operation, when action_naming lists extension
x-defaultMapping defaultMapping of a discriminator in OpenAPI 3.0 and 3.1 documents: the schema of the values whose discriminator value isn’t mapped
x-itemSchema itemSchema of a media type in OpenAPI 3.0 and 3.1 documents: the type of the items of a streamed response
x-apigenie.codegen.disabled since 0.12.0, true on an operation or its path item leaves the operation out
x-internal since 0.12.0, true on an operation or its path item leaves the operation out, unless internal_operations is true

The extensions can live in an overlay for this target instead of in the document, e.g. fetch.overlay.yaml:

overlay: 1.0.0
info:
  title: TypeScript names
  version: 1.0.0
actions:
  - target: $.components.schemas.Pet
    update:
      x-apigenie:
        codegen:
          name: Animal
apigenie-generator client fetch openapi.yaml --overlay fetch.overlay.yaml -o out

Limitations

The features of the conformance fixture the client doesn’t support yet are listed under Verification. Beyond them:

  • Form-encoded bodies don’t apply the encoding styles of their properties: an object property is sent as [object Object].
  • Callbacks, webhooks and links aren’t generated: they describe requests the server makes, or documentation.
  • Documents referencing other files must be bundled first with apigenie bundle.

Options

-c, –config

Path to the configuration file to use. See the “Configuration” section for more information.

–overlay OVERLAY

Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the extensions of the “Extensions” section. Can be repeated: the overlays apply in order, after those listed under commands.generate.client_fetch.overlay in the configuration file (with paths relative to it). Warnings and errors about a value an overlay set point to the overlay.

–strict

Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated) instead of a warning (OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.).

–check

Writes nothing: compares what the generator would write with the output directory, prints the files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See Check that generated code is up to date.

-o, –output

Required. Directory where the client is generated.

–package-name

Name of the npm package in package.json. Defaults to the document’s info.title in lower case with hyphens between words (Carpet Express Shipping API becomes carpet-express-shipping-api), or api-client when the title has no letters or digits.

–package-version

Version of the npm package in package.json. Defaults to the document’s info.version, or 0.0.0 when it is empty.

Configuration

version: '1.0'
commands:
  generate:
    client_fetch:
      layout: sources
      import_extension: ''
      action_naming: [id, extension, url]
      internal_operations: true
Option Type Default Description
layout package or sources package package writes an npm package (package.json, tsconfig.json, sources in src/); sources writes only the sources, directly in the output directory.
import_extension .js or '' .js Extension of relative imports between the generated files: .js for Node.js ES modules (NodeNext resolution), '' for bundlers.
action_naming id, extension, url, or a list of them [id, url] Where function names come from, in order of preference: the operationId, the x-apigenie.codegen.action-name extension, or the method and path.
internal_operations boolean false Since 0.12.0. Also generates the operations marked x-internal: true on the operation or its path item.

Verification

The codegen conformance suite runs this target on the Carpet Express OpenAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. All targets.

This target's support tier is Tier 1. It goes through all three levels before every release, with the goal of supporting every feature of the fixture. Its unsupported features are worked on first.

ResultsLevel 1Level 2Level 3
Release 0.12.0✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 29 supported, 0 not yet, 5 not checked✓ pass (Version 6.0.3, ESLint 10 + typescript-eslint 8)✓ 40 of 40 operations pass (node)
Development version✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 29 supported, 0 not yet, 5 not checkedruns before a releaseruns before a release
Was this helpful?