API Documentation

In this section, let’s explore how to document APIs in the Docusaurus site. REST APIs are generally present either as Markdown files or OpenAPI files. You need to import these OpenAPI/Markdown files to your Docusaurus site to generate the API documentation.

API Documentation with OpenAPI

APIs written in OpenAPI are generally YAML files (files with.yaml extension). You must place these YAML files within your Docusaurus project. The detailed procedure is as follows.

1. Open Command Prompt and execute the following command in your root directory (my-website).

npm install redoc  

2. Create a file ApiDocs.js within the src/components folder. Add the following code to it.

import React from 'react';

import { RedocStandalone } from 'redoc';

export default function ApiDocs() {

  return (

    <RedocStandalone

      specUrl="/openAPI/example.yaml" // note the leading slash, matches static folder path

      options={{ scrollYOffset: 50 }}

    />

  );

}

note

In my case, my API document name is example.yaml. It resides in a folder called OpenAPI. If your file/folder name varies, modify the specURI field accordingly.

3. Create a file called api.js within the src/pages folder. Add the following code to it.

import React from 'react';

import ApiDocs from '../components/ApiDocs';

export default function ApiPage() {

  return <ApiDocs />;

}

4. Store your API docs folder (openAPI/example.yaml in my case) within the static folder.

5. In Command Prompt, navigate to the root of your folder and execute the following command.

npm run start

6. Navigate to localhost:3000/api to view your API documentation.

Hosting Multiple OpenAPI Docs

In the previous section, we learnt how to host API documentation. However, if your API docs are hosted across multiple YAML files, you need to make a few changes to handle them. This section describes those changes.

Let’s assume that we have three YAML files called example1.yaml, example.yaml, and example3.yaml. I want to be able to select the required API through a drop-down menu once I navigate to localhost:3000/api. You can do this by tweaking the code in the ApiDocs.js file. The updated code is as follows.

import React, { useState } from 'react';
import { RedocStandalone } from 'redoc';

const specs = {
  example1: '/openAPI/example1.yaml',
  example2: '/openAPI/example2.yaml',
  example3: '/openAPI/example3.yaml',
};

export default function ApiDocs() {
  const [selectedSpec, setSelectedSpec] = useState('example1');

  const handleChange = (e) => {
    setSelectedSpec(e.target.value);
  };

  return (
    <div style={{ padding: '2rem' }}>
      <h2 style={{ fontSize: '1.5rem', marginBottom: '1rem' }}>
        Welcome to API Documentation
      </h2>
      <div style={{ marginBottom: '2rem' }}>
        <label htmlFor="spec-select" style={{ fontWeight: '600', marginRight: '0.5rem' }}>
          Select an API here:
        </label>
        <select
          id="spec-select"
          value={selectedSpec}
          onChange={handleChange}
          style={{
            fontSize: '1rem',
            padding: '0.5rem 1rem',
            borderRadius: '0.375rem',
            border: '1px solid #ccc',
            minWidth: '200px',
          }}
        >
          {Object.keys(specs).map((key) => (
            <option key={key} value={key}>
              {key}
            </option>
          ))}
        </select>
      </div>

      <RedocStandalone
        specUrl={specs[selectedSpec]}
        options={{ scrollYOffset: 50 }}
      />
    </div>
  );
}

In the const specs section, include your YAML file names (I have used the same content in all the three APIs, since this is just for a demo).

To view the APIs, you can navigate to this link.

API Documentation with Markdown

Since Docusaurus supports Markdown by default, the API docs written in Markdown do not require any additional configuration. You can just create a separate folder within the docs folder (recommended) and host your API docs. If you have multiple Markdown files, you can set the order in which they appear in the sidebar by following the steps mentioned in this section of the tutorial.

Markdown API Documentation Example

The following section displays how a sample API written in Markdown would be displayed in Docusaurus.

Simple API Documentation

This is a simple API that demonstrates basic operations with users.

---

Base URL

https://api.example.com/v1

---

👤 User Endpoints

Get All Users

GET /users

Returns a list of all users.