oazapfts

Generate TypeScript clients to tap into OpenAPI servers

OpenAPIScaffolding - generator
oazapfts/oazapfts@oazapfts/runtime

README

🍻 oazapfts!


Generate TypeScript clients to tap into OpenAPI servers.

undefined

Features


- AST-based:
  Unlike other code generators oazapfts does not use templates to generate code but uses TypeScript's built-in API to generate and pretty-print an abstract syntax tree.
- Fast: The CLI does not use any of the common Java-based tooling, so the code generation is super fast.
- Single file: All functions and types are co-located in one single self-contained file.
- Tree-shakeable: Individually exported functions allow you to bundle only the ones you actually use.
- Human friendly signatures: The generated API methods don't leak any HTTP-specific implementation details. For example, all optional parameters are grouped together in one object, no matter whether they end up in the headers, path or query-string.

Installation


  1. ```
  2. npm install oazapfts
  3. ```

Note

With version 3.0.0 oazapfts has become a runtime dependency and the generated code does no longer include all the fetch logic.

As of 6.0.0 the runtime has been moved to a separate package, @oazapfts/runtime.


Usage


  1. ```
  2. oazapfts <spec> [filename]

  4. Options:
  5. --exclude, -e tag to exclude
  6. --include, -i tag to include
  7. --optimistic
  8. --useEnumType
  9. --mergeReadWriteOnly
  10. --argumentStyle=<positional | object> (default: positional)
  11. ```

Where `` is the URL or local path of an OpenAPI or Swagger spec (in either json or yml) and `` is the location of the `.ts` file to be generated. If the filename is omitted, the code is written to stdout.

Options


- --optimistic generate a client in optimistic mode

- --useEnumType generate enums instead of union types

- --mergeReadWriteOnly by default oazapfs will generate separate types for read-only and write-only properties. This option will merge them into one type.

- --argumentStyle if "object" generated functions take single object style argument for parameters and requestBody, by default it's "positional" and parameters are separate as positional arguments

Consuming the generated API


For each operation defined in the spec the generated API will export a function with a name matching the operationId. If no ID is specified, a reasonable name is generated from the HTTP verb and the path.

  1. ```ts
  2. import * as api from "./my-generated-api.ts";
  3. const res = api.getPetById(1);
  4. ```

Note

If your API is large, and you want to take advantage of tree-shaking to exclude unused code, use individual named imports instead:


  1. ```ts
  2. import { getPetById } from "./my-generated-api.ts";
  3. ```

Fetch options


The last argument of each function is an optional [RequestOpts](https://github.com/oazapfts/oazapfts/blob/27b296c6fc28fec4869f1b7e1a4a5585ebbd5ee9/src/runtime/index.ts#L5) object that can be used to pass options to the fetch call, for example to pass additional headers or an AbortSignal to cancel the request later on.

  1. ```ts
  2. const res = getPetById(1, {
  3.   credentials: "include",
  4.   headers: {
  5.     Authorization: `Bearer ${token}`,
  6.   },
  7. });
  8. ```

You can also use this to override the default baseUrl or to provide a custom fetch implementation.

Note

Instead of passing custom options to each function call, consider overwriting the global defaults.


Optimistic vs. explicit responses


Oazapfts supports two different modes to handle results,
an explicit mode (the default) and an optimistic mode, that makes the response handling less verbose.