Git Product home page Git Product logo

oapi's Introduction

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

oapi's People

Contributors

brecert avatar insertish avatar sussycatgirl avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.