Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/insertish/oapi
Generate typed API libraries from OpenAPI specifications.
https://github.com/insertish/oapi
openapi revolt typescript
Last synced: 2 months ago
JSON representation
Generate typed API libraries from OpenAPI specifications.
- Host: GitHub
- URL: https://github.com/insertish/oapi
- Owner: insertish
- Created: 2022-03-20T11:16:41.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2023-08-16T00:29:01.000Z (over 1 year ago)
- Last Synced: 2024-10-15T04:22:59.334Z (3 months ago)
- Topics: openapi, revolt, typescript
- Language: TypeScript
- Homepage:
- Size: 32.2 KB
- Stars: 4
- Watchers: 3
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
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](https://bree.dev/) 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:
```typescript
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:
```typescript
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:
```typescript
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.
```typescript
new API({
baseURL: 'https://example.com',
authentication: {
rauth: 'session token'
}
})
```
## Setup Guide
Create a new project and configure it:
```sh
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:
```json
{
[...],
"scripts": {
"build": "oapilib && tsc"
}
}
```
**Note**: you may want to use `STRICT=1 opailib`, see "Strict Mode" below.
Setup Typescript:
```sh
yarn exec tsc -- --init
```
Change `tsconfig.json` to include:
```json
{
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src",
"declaration": true
}
}
```
Create a new `src` directory.
Now generate the library: (`src` folder will be overwritten!)
```sh
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.
```sh
REWRITE_ANYOF=1 oapilib
```