CLI and API

CLI

oasis-gen <SPEC> [-o <FILE>] [--lang <LANG>]

Argument	Meaning
SPEC	An OpenAPI document as a JSON or YAML file, or - for stdin
-o, --output FILE	Write to FILE instead of stdout
-l, --lang LANG	The target language; currently only typescript (the default)
-h, --help	Print help
-V, --version	Print the version

• oasis-gen follows $refs to other local files. It resolves them relative to the referencing document, or relative to the current directory when the document comes from stdin.
• If an error occurs, such as an invalid document, oasis-gen prints error: ... to stderr and exits with status 1.
• The output starts with a Generated by oasis-gen ... Do not edit. line.

Requirements

• Node.js 22 or later, for both the CLI and the generated client. The client also runs in browsers, tested in Chromium, Firefox, and WebKit, and in Bun.
• TypeScript 5.0 or later. The generated file needs lib ES2022 or later, plus either the dom lib or @types/node for fetch, Request, and Response.
• The file uses only erasable TypeScript syntax, so it also runs directly under Node's type stripping, which is on by default since Node.js 22.18.

The examples on this site import ./api.ts. This import requires allowImportingTsExtensions (Vite's templates set it) or Node's type stripping. Otherwise, import ./api.js or ./api, whichever your module resolution expects.

Installation

The npm package includes prebuilt binaries for macOS (arm64, x64), Linux (arm64, x64; statically linked, so they work with both glibc and musl), and Windows (arm64, x64). npm installs only the binary for your platform. Archives are also attached to each GitHub release. To build from source instead, run:

cargo install --git https://github.com/22mb/oasis

API

The generated file exports the following:

Export	Description
createClient(options?)	Creates a client; see Calling operations
auth(credentials)	Middleware that sends credentials as the document's security specifies; see Authentication
DecodeError	Thrown for a body that does not match its Content-Type; see Errors
Schema types, such as Pet and AccountRequest, and enum values, such as Kind	See Schemas
paths	Every operation's inputs, responses and the statuses each response covers, by path and method
schemas, components	The document's schemas by name; see Schemas
ApiResponse<Operation>	The result type of a call, from an operation in paths
Client<Paths>, ClientOptions, RequestOptions	The client, its options, and the fetch options of a call
Middleware, MiddlewareContext, OperationInfo	Middleware and the information it receives; see Middleware
Credential, SecurityRequirement, SecuritySchemeName	The types that auth uses
ServerSentEvent	One item of a text/event-stream response: { data, event?, id?, retry? }

ClientOptions

Option	Type	Description
baseUrl	string	Replaces every server in the document
headers	HeadersInit, or a function that returns it, possibly async	Sent with every request
middleware	Middleware[]	Wraps every request, outermost first
fetch	(request: Request) => Promise<Response>	Called instead of the global fetch

Middleware

type Middleware = (
  request: Request,
  next: (request: Request) => Promise<Response>,
  context: { operation: OperationInfo },
) => Promise<Response>;

OperationInfo field	Type	Description
method	string	The HTTP method, as used in the call
path	string	The path template, such as /pets/{petId}
operationId	string, optional	The operationId, when the document has one
security	SecurityRequirement[]	The security requirements that apply, in document order

Credential

type Credential =
  | string
  | ((
      scopes: string[],
      context: MiddlewareContext,
    ) => string | undefined | Promise<string | undefined>);

undefined or "" means that the credential is unavailable. auth also accepts undefined in place of a Credential.

Typing results

ApiResponse takes an operation from paths:

import type { ApiResponse, paths } from "./api.ts";

type GetPet = ApiResponse<paths["/pets/{petId}"]["GET"]>;