Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/foxfriends/openfetch

Fetch-like OpenAPI client library
https://github.com/foxfriends/openfetch

fetch-api openapi openapi3 swagger

Last synced: about 1 month ago
JSON representation

Fetch-like OpenAPI client library

Awesome Lists containing this project

README 

        
# OpenFetch



[![ci](https://github.com/foxfriends/openfetch/actions/workflows/ci.yaml/badge.svg)](https://github.com/foxfriends/openfetch/actions/workflows/ci.yaml)



Fetch-like OpenAPI client library. Supports [OpenAPI 3](https://swagger.io/specification/) only.



Install from NPM: `npm install openfetch`



## Usage



```js

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.