Fetch-like OpenAPI client library
README.md

OpenFetch #

ci

Fetch-like OpenAPI client library. Supports OpenAPI 3 only.

Install from NPM: npm install openfetch

Usage #

import * as openfetch from 'openfetch';

// Build an API based on the spec. Shown below are the default options:
const api = openfetch.create(SPEC, {
  // The base URL from which to make requests.
  url,
  // Enable logging. Validation errors will be logged to the console.
  logging: false,
  // The console, providing the log methods (only `warn` is used).
  console: window.console,
  // The default implementation of fetch to use for making requests.
  fetch: window.fetch,
});

// If your spec is hosted, it can be retrieved automatically.
const api = await openfetch.hosted('http://example.com', {
  // ... same opts as above
});

// Create an invocation context with credentials and such. The keys of the credentials
// object are names of security schemes, and the values are their values...
// *   HTTP Basic Auth expects the value to be `{ user, pass }`
// *   HTTP Bearer Auth expects the value to be just the token (i.e. not including the "Bearer" prefix)
// *   Other HTTP auth expects the full header value (i.e. including the scheme name)
// *   OAuth2 will pass the token via Autorization header
const invoke = openfetch.client({
  // Override the base URL from which to make requests
  url,
  // Override the implementation of `fetch` again. This value takes precedence over the one
  // passed to `create`, if both were provided.
  fetch,
  // The credentials to use to satisfy security requirements
  credentials: {},
});

// Invoke an operation by `operationId` (here: `getUser`):
// *   Parameter are supplied by name
// *   Options are the same as fetch, with a few being supplied automatically:
//     *   `Content-Type` will be determined automatically if the spec only defines one request body
//         type, otherwise it must be supplied via `headers`.
//     *   If `Content-Type` is JSON, `body` will be passed through `JSON.stringify`.
//         No processing will be done to any other bodies.
//     *   The `Authorization` header will be set automatically based on the security requirements.
//     *   Set the `Accept` header manually to specify which response format to receive.
const response = await invoke(api.getUser({ id: 'foxfriends' }, { headers, body }));

// The response is whatever is returned by the provided implementation of `fetch`. Refer to the
// relevant documentation on how to handle that response. In particular:
// *   The response body is not interpreted at all (e.g. JSON is not parsed automatically)
// *   The response status is not interpreted at all (e.g. 4XX/5XX reponses do not throw)
console.assert(response instanceof Response)

Points to note:

  • This package assumes your OpenAPI spec is valid/correct, and that you are (for the most part) calling it with sensible values. Undefined behaviour will occur if you deviate from spec.
  • The servers field of the spec is ignored. Provide a correct url on your own.
  • There is currently no support for any extensions, but to be able to implement those as plugins is something that is being considered.

Testing #

So far... very little testing has been done. Just a bit of manual stuff. Trust this project at your own risk for now, until I feel like writing a proper test suite.

Contributing #

Contributions are welcome! Please send a PR or create issues if you would like something improved.