Typoas is an OpenAPI 3.X generator for Typescript. It's inspired by openapi-generator but is written in Typescript for Typescript. The generator uses the Typescript AST to generate code instead on relaying on templates which allows better schemas definitions and other cool stuff.
Main features are:
- Fully typed
- Support for
allOf
,oneOf
andanyOf
schemas. - References
$ref
handling (with cyclic refs) - Uses
fetch
api (can be customized) - Automatically convert
format: 'date-time'
to JSDate
- Handle API Key, HTTP Config and OAuth21 auth security schemes
- JSDoc for schemas and operations
- And more...
1: OAuth2 scheme does not handle flows to retrieve an
accessToken
. You need to provide your ownaccessToken
through theprovider.getConfig()
function.
The project is split into 3 parts:
@typoas/generator
is used to generate the API specific code.@typoas/cli
is a CLI entry point built on top of@typoas/generator
.@typoas/runtime
is the package that will be used by the generated code.
It will generate a single TS file containing all the code specific to the underlying API.
This file only has a single dependency on @typoas/runtime
.
You need to manually add @typoas/runtime
to your dependencies
.
It handles common things like serialization/authentification
You can generate the TS client from the spec from the command line:
yarn dlx @typoas/cli generate -i my-spec.json -n MyClient -o src/client.ts
npx @typoas/cli generate -i my-spec.json -n MyClient -o src/client.ts
Here is a short list of supported command line options:
-i, --input [path/url] Path or URL to the OpenAPI JSON specification (yaml/json format)
-o, --output [path] Path where to write the generated TS file
-n, --name Class name of the generated client
-e,--generate-enums Generate enums instead of literal string types where possible
--js-doc, --no-js-doc Whether to add JS Doc to the generated code (default: true)
--only-types Use it to only generate types in #components/schemas/
--version Output the version number
-h, --help Display help for command
or you can use it in code:
import cli from '@typoas/cli';
await cli.run(
[
'generate',
'-i',
'https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.yaml',
'-o',
`./src/github.ts`,
'-n',
`GithubClient`,
],
{
stdin: process.stdin,
stdout: process.stdout,
stderr: process.stderr,
},
);
The API is still at an alpha stage, so it may break between minors.
It uses typescript
API to generate usable code:
import { readFileSync, writeFileSync } from 'fs';
import { createPrinter, NewLineKind, SourceFile } from 'typescript';
import { generateClient, getStringFromSourceFile } from '@typoas/generator';
const specs = JSON.parse(readFileSync('path/to/github-openapi.json', 'utf8'));
const src = generateClient(specs, 'GithubClient');
const data = getStringFromSourceFile(src);
writeFileSync('./src/client.ts', data, 'utf8');
Once the file is generated you'll be able to use it like this:
import fetch from 'node-fetch';
import { ServerConfiguration } from '@typoas/runtime';
import { GithubClient } from './client';
// Inject fetch polyfill into NodeJS env.
if (!globalThis.fetch) {
// @ts-ignore
globalThis.fetch = fetch;
}
const client = new GithubClient(
new ServerConfiguration('https://api.github.com', {}),
);
client
.pullsList({
repo: 'typoas',
owner: 'embraser01',
})
.then((list) => console.log('List of PRs', list))
.catch((err) => console.error('Error while getting PRs', err));
You can find examples in the examples
folder.
Here is some notes on some known issues.
Typoas has partial support for serialization specified here: https://swagger.io/docs/specification/serialization/
- It does support array serialization for query.
- It does NOT support serialization for path parameters with
style
label
ormatrix
. - It does NOT support serialization for query parameters with nested objects. It will be JSON.stringify
- It does NOT support serialization for headers or cookie parameters.
On query serialization, there can only be one style for a full operation. The first query param will set the style for the whole operation.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.