Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/anttiviljami/react-openapi-client
Consume OpenAPI-enabled APIs with React Hooks
https://github.com/anttiviljami/react-openapi-client
hacktoberfest openapi react react-hooks swagger
Last synced: 15 days ago
JSON representation
Consume OpenAPI-enabled APIs with React Hooks
- Host: GitHub
- URL: https://github.com/anttiviljami/react-openapi-client
- Owner: anttiviljami
- License: mit
- Created: 2020-04-19T14:01:41.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T04:39:54.000Z (almost 2 years ago)
- Last Synced: 2024-10-10T12:07:52.068Z (about 1 month ago)
- Topics: hacktoberfest, openapi, react, react-hooks, swagger
- Language: TypeScript
- Homepage:
- Size: 2.27 MB
- Stars: 57
- Watchers: 5
- Forks: 10
- Open Issues: 29
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# React OpenAPI Client
[](https://github.com/anttiviljami/react-openapi-client/actions?query=workflow%3ACI)
[](https://www.npmjs.com/package/react-openapi-client)
[](https://bundlephobia.com/package/react-openapi-client)
[](https://github.com/anttiviljami/react-openapi-client/blob/master/LICENSE)
[](https://buymeacoff.ee/anttiviljami)
Consume OpenAPI-enabled APIs with React Hooks
Uses [`openapi-client-axios`](https://www.npmjs.com/package/openapi-client-axios) under the hood.
## Why?
You can do this:
```jsx
import React, { useEffect } from 'react';
import { useOperation } from 'react-openapi-client';
const MyComponent = (props) => {
const { loading, data, error } = useOperation('getPetById', props.id);
// ...
};
```
Instead of:
```jsx
import React, { useEffect, useState } from 'react';
const MyComponent = (props) => {
const [loading, setLoading] = useState(false);
const [data, setData] = useState();
const [error, setError] = useState();
useEffect(() => {
(async () => {
setLoading(true);
try {
const res = await fetch(`https://petstore.swagger.io/api/v3/pet/${props.id}`, {
method: 'GET',
headers: {
'Content-Type': 'application/json',
},
credentials: 'include',
});
const data = await res.json();
setData(data);
} catch (err) {
setError(err);
}
setLoading(false);
})();
}, [props.id]);
// ...
};
```
## Getting Started
Install `react-openapi-client` as a dependency
```
npm install --save react-openapi-client axios
```
Wrap your React App with an `OpenAPIProvider`, passing your OpenAPI definition as a prop.
```jsx
import React from 'react';
import { render } from 'react-dom';
import { OpenAPIProvider } from 'react-openapi-client';
const App = () => (
);
```
Now you can start using the `useOperation` and `useOperationMethod` hooks in your components.
```jsx
import { useOperation } from 'react-openapi-client';
const PetDetails = (props) => {
const { loading, data, error } = useOperation('getPetById', props.id);
if (loading) {
return
Loading...;
}
if (error) {
return
Error: {error};
}
return (
{data.name}
-
id: {data.id}
-
status: {data.status}
);
};
```
See a full Create-React-App example under [`examples/`](https://github.com/anttiviljami/react-openapi-client/tree/master/examples/)
## useOperation hook
The `useOperation` hook is a great way to declaratively fetch data from your API.
Important! Calling `useOperation()` always immediately calls the API endpoint.
Parameters:
`useOperation` passes the arguments to an OpenAPI Client Axios [`Operation Method`](https://github.com/anttiviljami/openapi-client-axios#operation-methods)
matching the operationId given as the first parameter.
- [**operationId**](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#fixed-fields-8) (string) Required. the operationId of the operation to call
- [**parameters**](https://github.com/anttiviljami/openapi-client-axios#parameters) (object | string | number) Optional. Parameters for the operation
- [**data**](https://github.com/anttiviljami/openapi-client-axios#data) (object | string | Buffer) Optional. Request payload for the operation
- [**config**](https://github.com/anttiviljami/openapi-client-axios#config-object) (AxiosRequestConfig) Optional. Request payload for the operation
Return value:
`useOperation` returns an object containing the following state properties:
- **loading** (boolean) whether the API request is currently ongoing.
- **data** (any) the parsed response data for the operation.
- **response** (any) the raw axios response object for the operation.
- **error** (Error) contains an error object, in case the request fails
- **api** (OpenAPIClientAxios) reference to the API client class instance
Example usage:
```javascript
const { loading, data, error } = useOperation('getPetById', 1, null, { headers: { 'x-api-key': 'secret' } });
```
## useOperationMethod hook
The `useOperationMethod` hook can be used to obtain a callable operation method.
Unlike `useOperation`, calling `useOperationMethod()` has no side effects.
Parameters:
`useOperationMethod` gets the corresponding OpenAPI Client Axios [`Operation Method`](https://github.com/anttiviljami/openapi-client-axios#operation-methods)
matching the operationId.
- [**operationId**](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#fixed-fields-8) (string) Required. the operationId of the operation to call
Return value:
`useOperationMethod` returns a tuple (javascript array), where the first
element is the callable operation method, and the second method contains the
same object as `useOperation`'s return value.
See [OpenAPI Client Axios documentation](https://github.com/anttiviljami/openapi-client-axios/blob/master/DOCS.md#operation-method)
for more details on how to use the Operation Methods.
Example usage:
```javascript
const [createPet, { loading, response, error }] = useOperationMethod('createPet');
```
## OpenAPIProvider
The `OpenAPIProvider` component provides `OpenAPIContext` to all nested components in the
React DOM so they can use the `useOperation` and `useOperationMethod` hooks.
Internally, the Provider instantiates an instance of OpenAPIClientAxios, which
is then used by the hooks to call the API operations.
In addition to the definition file, you can pass any [constructor options](https://github.com/anttiviljami/openapi-client-axios/blob/master/DOCS.md#class-openapiclientaxios)
accepted by OpenAPIClientAxios as props to the `OpenAPIProvider` component.
Example usage:
```jsx
const App = () => (
)
```
You can also access the `OpenAPIClientAxios` instance by using the React `useContext` hook:
```jsx
import React, { useContext } from 'react';
import { OpenAPIContext } from 'react-openapi-client';
const MyComponent = () => {
const { api } = useContext(OpenAPIContext);
const client = api.client;
const definition = api.definition;
// ...
}
```
## Contributing
React OpenAPI Client is Free and Open Source Software. Issues and pull requests are more than welcome!
[
](https://spiceprogram.org/oss-sponsorship)