Generate TypeScript clients to tap into OpenAPI servers.
- 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.
npm install oazapfts
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
.
oazapfts <spec> [filename]
Options:
--exclude, -e tag to exclude
--include, -i tag to include
--optimistic
--useEnumType
--mergeReadWriteOnly
--argumentStyle=<positional | object> (default: positional)
Where <spec>
is the URL or local path of an OpenAPI or Swagger spec (in either json or yml) and <filename>
is the location of the .ts
file to be generated. If the filename is omitted, the code is written to stdout.
-
--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
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.
import * as api from "./my-generated-api.ts";
const res = api.getPetById(1);
Note If your API is large, and you want to take advantage of tree-shaking to exclude unused code, use individual named imports instead:
import { getPetById } from "./my-generated-api.ts";
The last argument of each function is an optional RequestOpts
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.
const res = getPetById(1, {
credentials: "include",
headers: {
Authorization: `Bearer ${token}`,
},
});
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.
Oazapfts supports two different modes to handle results, an explicit mode (the default) and an optimistic mode, that makes the response handling less verbose.
By default, each function returns an ApiResponse
object that exposes the status
code, response headers
and the data
.
Note This mode is best suited for APIs that return different types for different response codes or APIs where you need to access not only the response body, but also the response headers. If your API is simple, and you don't need this flexibility, consider using the optimistic mode instead.
In explicit mode, each function returns a Promise for an ApiResponse
which is an object with a status
and a data
property, holding the HTTP status code and the properly typed data from the response body.
Since an operation can return different types depending on the status code, the actual return type is a union of all possible responses, discriminated by their status.
Consider the following code generated from the petstore.json
example:
/**
* Find pet by ID
*/
export function getPetById(petId: number, opts?: Oazapfts.RequestOpts) {
return oazapfts.fetchJson<
| {
status: 200;
data: Pet;
}
| {
status: 400;
data: string;
}
| {
status: 404;
}
>(`/pet/${encodeURIComponent(petId)}`, {
...opts,
});
}
In this case, the data
property is typed as Pet|string
. We can use a type guard to narrow down the type to Pet
:
const res = await api.getPetById(1);
if (res.status === 200) {
const pet = res.data;
// pet is properly typed as Pet
}
if (res.status === 404) {
const message = res.data;
// message is a string
} else {
// handle the error
}
The above code can be simplified by using the handle
helper:
import { handle } from "@oazapfts/runtime";
await handle(api.getPetById(1), {
200(pet) {
// pet is properly typed as Pet
},
404(message) {
// message is as string
},
});
The helper will throw an HttpError
error for any unhandled status code, unless you add a default
handler:
await handle(api.getPetById(1), {
200(pet) {
// ...
},
default(status, data) {
// handle error
},
});
You can opt into the optimistic mode by using the --optimistic
command line argument.
In this mode, each function will return a Promise for the happy path, i.e. the type specified for the first 2xx
response.
Looking back at our Pet Store example from ab