@spacebarchat/oapi
v0.1.21
Published
API Library Generator for OpenAPI
Downloads
1
Readme
OAPI Client
This is a CLI for auto-generating an API library for a given OpenAPI spec which uses JSON primarily and conforms to Revolt's API style.
Thank you to bree for helping me figure out all the especially difficult types.
Goals
- Commit programming atrocities internally.
- Pretend everything is fine externally.
- Provide a simple strongly typed API experience to the user.
Example
Here's what you can achieve with this library:
import { API } from 'your-api';
let id = 'user_id';
// By default, we use the first server specified in the API spec.
new API()
// Path parameters are specified using template strings.
.get(`/users/${id}`)
.then(user => {
// User is still fully typed!
return user.username;
})
.then(console.log);
Conflict resolution is also automatic, so conflicting prefixes will not cause issues:
import { API } from 'your-api';
// For a route /some/{string}:
new API()
.get('/some/this is an example')
.then(x => {
x // number
})
// For a route /some/{string}/conflicting:
new API()
.get('/some/this is an example/conflicting')
.then(x => {
x // string
})
You can also provide your query and body parameters at the same time:
import { API } from 'your-api';
// PATCH /users/@me?preserve=true
// Body: { username: string }
new API()
.patch(`/users/@me`, {
// Specify query parameters
preserve: true,
// Or body parameters
username: 'something'
});
This removes the overhead of having to remember exactly what goes where and provides a much nicer (and still strongly typed) API experience.
Currently this only supports rauth and Revolt authentication, but you can still provide your own Axios config or add your own authentication.
new API({
baseURL: 'https://example.com',
authentication: {
rauth: 'session token'
}
})
Setup Guide
Create a new project and configure it:
yarn init
yarn add @insertish/oapi axios lodash.defaultsdeep
yarn add --dev typescript openapi-typescript @types/lodash.defaultsdeep
Place your OpenAPI specification at the root of your API library at OpenAPI.json
.
Update your package.json
to include the following:
{
[...],
"scripts": {
"build": "oapilib && tsc"
}
}
Note: you may want to use STRICT=1 opailib
, see "Strict Mode" below.
Setup Typescript:
yarn exec tsc -- --init
Change tsconfig.json
to include:
{
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src",
"declaration": true
}
}
Create a new src
directory.
Now generate the library: (src
folder will be overwritten!)
yarn build
Replace anyOf
with oneOf
If your spec uses anyOf
, the values are mapped as an intersection while you may actually want all of these values to be treated as if they were oneOf
, or otherwise a union.
You can specify the environment variable REWRITE_ANYOF
to any truthy value.
REWRITE_ANYOF=1 oapilib