Now with Partition Management

    react-openapi-client
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.2 • Public • Published

    React OpenAPI Client

    CI npm version bundle size License Buy me a coffee

    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!

    The Chilicorn

    Install

    npm i react-openapi-client

    DownloadsWeekly Downloads

    471

    Version

    0.2.2

    License

    MIT

    Unpacked Size

    31.2 kB

    Total Files

    15

    Last publish

    Collaborators

    • anttiviljami