0.1.0-alpha.7

@zerolith/client/generate

Import from @zerolith/client/generate. Generated from the source; every signature below is what the published types declare.

Functions

generateClient

function generateClient(document: OpenApiDocument, options?: GenerateOptions): string

Generates the contract module for an OpenAPI 3.x document given as a parsed object (JSON; convert YAML first). Schemas under components.schemas become exported types, every operation becomes an entry of the Api interface named by its operationId (or by its method and path), and routes carries the method and path of each. Header and cookie parameters, security, and non-local references are left out; the client sends headers through its options. A schema whose type name would clash is written under the first free name with a number added, as Record2, with a comment that says why, and every $ref to it uses that name: one that another schema takes first, as note-item and note_item both give NoteItem, one named like the interface of the operations or the RouteTable the module imports, and one named like a built-in type the module writes, such as Record for an object of free keys or Blob for a binary response. A schema named like a built-in the module does not write keeps its name.

Source: packages/client/src/generate.ts:669

Interfaces

SchemaObject

interface SchemaObject

A JSON Schema object as OpenAPI 3.1 and later carry it (draft 2020-12 plus the OAS vocabulary).

  • $ref?: string: A reference to #/components/schemas/<name>, rendered as that component's generated type, intersected with the keywords beside it that shape a type, such as properties, as OpenAPI 3.1 allows; any other target fails generation.
  • type?: string | string[]: The JSON type, or since OpenAPI 3.1 an array of types rendered as a union; integer renders as number, and when it is absent the object or array keywords imply one, else the type is unknown.
  • nullable?: boolean: The OpenAPI 3.0 flag that also allows null; when true, null joins the type.
  • enum?: unknown[]: The allowed values, rendered as a union of their literal types; it takes precedence over type, and intersects with a composition keyword or $ref beside it.
  • const?: unknown: The single allowed value (OpenAPI 3.1 and later), rendered as its literal type; it takes precedence over enum and type, and intersects with a composition keyword or $ref beside it.
  • properties?: Record<string, SchemaObject>: The object's properties, each generated as a member that is optional unless required lists it, with the property's description as its doc comment.
  • required?: string[]: The names in properties that must be present; every other property is generated as optional.
  • additionalProperties?: boolean | SchemaObject: The schema of keys beyond properties, rendered as a Record<string, ...> joined to them with &; true allows unknown values, and false makes an object without properties Record<string, never>.
  • items?: SchemaObject: The schema of each array element, rendered as T[], or unknown[] without it; beside prefixItems it types the elements after the tuple.
  • prefixItems?: SchemaObject[]: The schemas of the leading array elements by position (OpenAPI 3.1 and later), rendered as a tuple; without items the tuple has no rest element.
  • oneOf?: SchemaObject[]: Alternatives of which exactly one matches, rendered as a union; it takes precedence over anyOf and allOf, and the keywords beside it that shape a type, such as properties, intersect with it.
  • anyOf?: SchemaObject[]: Alternatives of which at least one matches, rendered as a union unless oneOf is present; the keywords beside it that shape a type, such as properties, intersect with it.
  • allOf?: SchemaObject[]: Schemas that all match, rendered as an intersection unless oneOf or anyOf is present; the keywords beside it that shape a type, such as properties, join the intersection.
  • description?: string: Becomes the doc comment on a component schema's generated type, ahead of title, and on an object property's member.
  • title?: string: The doc comment on a component schema's generated type when description is absent; the type's name comes from the component's key, not from title.

Source: packages/client/src/generate.ts:8

ParameterObject

interface ParameterObject

A Parameter Object or a reference to one.

  • $ref?: string: A reference to #/components/parameters/<name>, which replaces this object; any other target, or a missing one, fails generation.
  • name?: string: The member's key in the generated params or query, matching the {name} placeholder for a path parameter; a parameter without name or in fails generation.
  • in?: "query" | "querystring" | "header" | "path" | "cookie": Where the parameter travels: path fills params, query adds a member to query, querystring (OpenAPI 3.2) lets query take any key, and header and cookie are left out.
  • required?: boolean: Makes a query parameter's member, and the whole query input, required; path parameters are generated as required either way, since OpenAPI demands true for them.
  • description?: string: The doc comment on the parameter's generated member.
  • schema?: SchemaObject: The schema of the value, rendered as the member's type; without it or content, the type is unknown.
  • content?: Record<string, MediaTypeObject>: The single media type entry OpenAPI allows in place of schema; when schema is absent, the entry's schema gives the member's type.

Source: packages/client/src/generate.ts:43

MediaTypeObject

interface MediaTypeObject

A Media Type Object.

  • schema?: SchemaObject: The content's schema, read for a JSON media type in a body and for any media type in a parameter's content; when absent, the type is unknown.

Source: packages/client/src/generate.ts:62

RequestBodyObject

interface RequestBodyObject

A Request Body Object or a reference to one.

  • $ref?: string: A reference to #/components/requestBodies/<name>, which replaces this object; any other target, or a missing one, fails generation.
  • description?: string: A brief description of the body; the generator does not carry it into the output.
  • required?: boolean: Makes the generated body input required; OpenAPI's default is false, which generates it as optional.
  • content?: Record<string, MediaTypeObject>: The body by media type, where a JSON type takes precedence and gives its schema's type; otherwise multipart/form-data gives FormData, application/x-www-form-urlencoded gives URLSearchParams, text/* gives string, and any other type gives BodyInit.

Source: packages/client/src/generate.ts:69

ResponseObject

interface ResponseObject

A Response Object or a reference to one.

  • $ref?: string: A reference to #/components/responses/<name>, which replaces this object; any other target, or a missing one, fails generation.
  • description?: string: A description of the response; the generator does not carry it into the output.
  • content?: Record<string, MediaTypeObject>: The response body by media type: a JSON type, when present, gives its schema's type, text/* gives string, any other type gives Blob, as the client reads it, and no content gives undefined.

Source: packages/client/src/generate.ts:82

OperationObject

interface OperationObject

An Operation Object.

  • operationId?: string: Names the operation's entry in Api and routes, in camelCase; without it the name comes from the method and path, such as putNotesById for PUT /notes/{id}, and two entries with one name fail generation.
  • summary?: string: The first paragraph of the doc comment on the operation's entry in Api.
  • description?: string: Follows summary in the doc comment on the operation's entry in Api.
  • deprecated?: boolean: When true, the doc comment on the operation's entry ends with @deprecated.
  • parameters?: ParameterObject[]: The operation's parameters, merged with the path item's; one with the same name and in as a path item parameter replaces it.
  • requestBody?: RequestBodyObject: The request body, generated as the entry's body input; without it the entry has no body.
  • responses?: Record<string, ResponseObject>: The responses by status code; output is the union of every 2xx response, including 2XX, or of default when there is none, and unknown without either.

Source: packages/client/src/generate.ts:93

PathItemObject

interface PathItemObject

A Path Item Object.

  • $ref?: string: A reference to #/components/pathItems/<name>, which replaces this item; any other target, or a missing one, fails generation.
  • summary?: string: A summary meant for every operation on the path; the generator does not carry it into the output.
  • description?: string: A description meant for every operation on the path; the generator does not carry it into the output.
  • parameters?: ParameterObject[]: Parameters shared by every operation on the path; an operation's own parameter with the same name and in replaces one.
  • get?: OperationObject: The GET operation on this path.
  • put?: OperationObject: The PUT operation on this path.
  • post?: OperationObject: The POST operation on this path.
  • delete?: OperationObject: The DELETE operation on this path.
  • options?: OperationObject: The OPTIONS operation on this path.
  • head?: OperationObject: The HEAD operation on this path.
  • patch?: OperationObject: The PATCH operation on this path.
  • trace?: OperationObject: The TRACE operation on this path.
  • query?: OperationObject: The QUERY operation on this path (OpenAPI 3.2): a safe, idempotent request that carries a body.
  • additionalOperations?: Record<string, OperationObject>: Operations for other HTTP methods (OpenAPI 3.2), keyed by method name such as COPY; each key is lowercased, and one that is not a valid method token fails generation.

Source: packages/client/src/generate.ts:112

OpenApiDocument

interface OpenApiDocument

The parts of an OpenAPI document the generator reads.

  • openapi: string: The OpenAPI version, such as 3.1.0; a value that does not start with 3. fails generation.
  • info?: { title?: string; version?: string }: The API's title and version, which the generated file's header comment names as its source.
  • paths?: Record<string, PathItemObject>: Path templates mapped to their items; every operation under them becomes an entry of Api and routes, sorted by path.
  • components?: { schemas?: Record<string, SchemaObject>; parameters?: Record<string, ParameterObject>; requestBodies?: Record<string, RequestBodyObject>; responses?: Record<string, ResponseObject>; pathItems?: Record<string, PathItemObject> }: Reusable objects: each entry of schemas becomes an exported type named after its key, and $ref values resolve into the other sections.

Source: packages/client/src/generate.ts:145

GenerateOptions

interface GenerateOptions

Options for generateClient.

  • clientSpecifier?: string: The module the generated file imports RouteTable from. Defaults to @zerolith/client.
  • apiName?: string: The name of the generated contract interface. Defaults to Api.

Source: packages/client/src/generate.ts:164