hrayr-s / react-openapi-client

Consume OpenAPI-enabled APIs with React Hooks

React OpenAPI Client

Consume OpenAPI-enabled APIs with React Hooks

Uses openapi-client-axios under the hood.

Why?

You can do this:

import React, { useEffect } from 'react';
import { useOperation } from 'react-openapi-client';

const MyComponent = (props) => {
  const { loading, data, error } = useOperation('getPetById', props.id);
  // ...
};

Instead of:

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.

import React from 'react';
import { render } from 'react-dom';
import { OpenAPIProvider } from 'react-openapi-client';

const App = () => (
  <OpenAPIProvider definition="http://petstore.swagger.io:8080/api/v3/openapi.json">
    <PetDetails id={1} />
  </OpenAPIProvider>
);

Now you can start using the useOperation and useOperationMethod hooks in your components.

import { useOperation } from 'react-openapi-client';

const PetDetails = (props) => {
  const { loading, data, error } = useOperation('getPetById', props.id);

  if (loading) {
    return <div>Loading...</div>;
  }

  if (error) {
    return <div>Error: {error}</div>;
  }

  return (
    <div className="App">
      <img src={data.image} alt={data.name} />
      <h3>{data.name}</h3>
      <ul>
        <li>
          <strong>id:</strong> {data.id}
        </li>
        <li>
          <strong>status:</strong> {data.status}
        </li>
      </ul>
    </div>
  );
};

See a full Create-React-App example under 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 matching the operationId given as the first parameter.

• operationId (string) Required. the operationId of the operation to call
• parameters (object | string | number) Optional. Parameters for the operation
• data (object | string | Buffer) Optional. Request payload for the operation
• config (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:

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 matching the operationId.

• operationId (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 for more details on how to use the Operation Methods.

Example usage:

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 accepted by OpenAPIClientAxios as props to the OpenAPIProvider component.

Example usage:

const App = () => (
  <OpenAPIProvider definition="http://petstore.swagger.io:8080/api/v3/openapi.json" axiosConfigDefaults={{ withCredentials: true }}>
    <ApplicationLayout />
  </OpenAPIProvider>
)

You can also access the OpenAPIClientAxios instance by using the React useContext hook:

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!