SDK Generation

[erunion]

🧰 What's being changed?

This completely rewrites the existing api module to focus on the autogeneration of SDKs from an OpenAPI 3.x document. For example:

const sdk = require('./src')('https://raw.githubusercontent.com/readmeio/oas/master/packages/examples/3.0/yaml/readme.yaml');

sdk
  .auth('readmeApiToken')
  .getChangelogs({
    perPage: 10,
    page: 1
  })
  .then(res => res.json())
  .then(res => {
    console.log(`there are ${res.length} changelogs`);
    console.log(res[0]);
  });

📓 How does it work?

Proxies! Proxies are a recent addition to JS that allows for one to create wildcard-y object accessors. With this we can create an SDK proxy that has the base methods all SDKs have (like .auth()), and then automatically allow for the end-user to access operations like .getChangelogs() or .get() on the chain.

What'll happen when a user first makes a request via .getChangelogs() is that we'll fetch the OpenAPI definition they supplied, process it, cache it into node_modules/.cache/api, and run through the definition to add any present operation IDs as chainable methods (like .getChangelogs() on the Proxy. On subsequent requests, the OpenAPI definition is re-fetched from the local cache, and re-added to the Proxy.

It's like magic.

🎙How do I make requests?

With the chained operation IDs, or HTTP verb methods like GET or POST, that are automatically generated onto the SDK, you can pass them parameters and request body payloads by supplying either a body object or array, and/or a metadata (parameters) object. The SDK will then determine, according to the OpenAPI definition, what goes where. For example:

1. Just metadata: sdk.showPetById({ petId: 1234 }).then(...)
2. Just body: sdk.createPets({ name: 'Buster' }).then(...)
3. Both: sdk.updatePet({ name: 'Buster 2' }, { petId: 1234 }).then(...)

🧪 Testing

To test out the SDK, give it an OpenAPI URL or local file and go wild.

[domharrington]

Some really great progress here! 💪

[erunion]

@gkoberger @domharrington I decided to sleep on it and I'm going to stick with the arg format as body, metadata.

A major portion of API requests will only constitute metadata, and making a request with get(metadata) will work as expected. And for those that require both, the body that's supplied is the more important part of the request and makes sense to be the primary argument and take precedence over metadata.

[kanadgupta]

Just a few comments on the README.md — haven't taken a look at the code yet!

[kanadgupta]

whoooooosh

[erunion]

We need an astronaut Owlbert.

[domharrington]

What's support for Proxy like?

This is incredible. Ran it locally and it worked like a charm by fetching the spec file and everything. I wasn't sure if Proxy would be possible, and I still don't completely understand how it works but it's amazing.

Really hyped for the release of this! 💪

[domharrington]

Can we get code coverage sent up to codecov.io?

[domharrington]

This is really nifty!

[domharrington]

[erunion]

@domharrington Proxy is supported currently in Node 6+, every non-IE browser, and Safari (though it doesn't support getPrototypeOf, but I'm not using that here). The SDK could likely be reconfigured to work in a browser environment, but that's going to require some thought into how it handles file caching since it relies on the fs module.