Using the ShopCore API as the running example

This tutorial walks through building a documentation website for a REST API, starting from an empty folder and ending with a working, browsable API reference. No prior experience with Docusaurus is assumed.

What You'll Build

By the end of this tutorial, you'll have a live documentation website with a written OpenAPI specification for your API, an interactive reference page for every endpoint (with a working "Try it out" button), and space for your own written guides sitting right alongside the generated reference pages.

Here's the high-level path:

•      Create a new Docusaurus website

•      Install the OpenAPI documentation plugin

•      Add your API's OpenAPI specification file

•      Generate reference pages automatically from that spec

•      Add your own written guides

•      Preview it locally, then deploy it

Note: You don't need to know what "OpenAPI" means yet — it's explained in Step 3, right where you'll use it.

Before You Start

You'll need three things installed on your computer:

•      Node.js (version 18 or higher) — this runs Docusaurus

•      A code editor — VS Code is a common free choice

•      A terminal — Terminal on Mac, or Command Prompt / PowerShell on Windows

To check whether Node.js is already installed, open a terminal and run:

node -v

If you see a version number like v18.x.x or higher, you're set. If not, download and install it from nodejs.org before continuing.

Step 1: Create a New Docusaurus Site

Docusaurus is a tool that turns folders of Markdown files into a polished documentation website — it handles the navigation, search, styling, and structure for you.

In your terminal, navigate to where you want the project to live, then run:

npx create-docusaurus@latest shopcore-docs classic --typescript

cd shopcore-docs

npm run start

The first command creates a new folder called shopcore-docs with a working starter site inside it. The second moves your terminal into that folder. The third starts a local preview server.

Open your browser to http://localhost:3000. If you see the default Docusaurus welcome page, this step is done. Leave this running — you'll refresh this page throughout the tutorial. Open a second terminal tab for the remaining commands.

Step 2: Install the OpenAPI Plugin

Docusaurus doesn't understand APIs out of the box — it just renders Markdown. The plugin below teaches it how to read an API specification and turn it into reference pages automatically.

In your project folder, run:

npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs

This adds two packages: the plugin that does the page generation, and a theme that styles those pages (including the interactive "Try it out" panel) to match the rest of your site.

Step 3: Get Your API Description Ready (OpenAPI Spec)

An OpenAPI spec is a single file — usually YAML — that lists every endpoint your API has, what data each one expects, and what it returns. It's the one source of truth the plugin reads to build all your reference pages.

Create a folder for it inside your project:

mkdir openapi

If you already have a Postman collection for your API, you can convert it into a starting OpenAPI file instead of writing one from scratch:

npm install -g postman-to-openapi

p2o path/to/your-collection.json -f openapi/shopcore.yaml

Open the generated openapi/shopcore.yaml file in your editor afterward. Auto-converted specs are usually bare-bones, so go through it and:

•      Add a tags field to each endpoint (for example: Auth, Products, Orders) — this controls how your sidebar is grouped later

•      Fill in a short description for each endpoint

•      Set the servers.url field to your API's real base URL

Note: If you're writing the spec by hand instead of converting one, the same rules apply: tag every endpoint, describe every field, and keep the file inside the openapi folder.

Step 4: Connect the Spec to Docusaurus

Now tell Docusaurus where to find your spec file and where to put the pages it generates. Open docusaurus.config.ts in your project's root folder and update it to match the following:

const config = {

  themes: ["docusaurus-theme-openapi-docs"],

  presets: [

[

   "classic",

   {

     docs: {

       docItemComponent: "@theme/ApiItem",

       sidebarPath: "./sidebars.ts",

     },

   },

],

  ],

  plugins: [

[

      "docusaurus-plugin-openapi-docs",

   {

     id: "api",

     docsPluginId: "classic",

     config: {

       shopcore: {

         specPath: "openapi/shopcore.yaml",

         outputDir: "docs/api",

         sidebarOptions: {

           groupPathsBy: "tag",

           categoryLinkSource: "tag",

         },

       },

     },

   },

],

  ],

};

export default config;

The docItemComponent line is easy to miss but required — without it, the generated pages won't display their interactive elements correctly.

Step 5: Generate the Reference Pages

With the config saved, generate the actual documentation pages by running:

npm run docusaurus gen-api-docs shopcore

This reads your spec and writes a set of .mdx files into docs/api — one page per endpoint, plus an overview page. Next, generate the sidebar entries so those pages show up in your site's navigation:

npm run docusaurus gen-api-docs:sidebar

Refresh your browser at localhost:3000. You should now see an API section in the sidebar, grouped by the tags you set in Step 3, with every endpoint listed.

Step 6: Add Your Own Written Guides

The generated pages are pure reference — accurate, but dry. Real documentation usually needs plain-language guides alongside that reference: how to authenticate, common errors, a first-request walkthrough. Add these as ordinary Markdown files anywhere under the docs folder, for example:

docs/

intro.md           <- what the API is, in plain terms

getting-started.md <- first request, step by step

guides/

authentication.md <- how login and tokens work

error-handling.md <- what error responses mean

api/               <- generated — don't hand-edit these

Link between your guides and the generated pages using normal Markdown links, and use a sidebar_position number in each file's frontmatter to control where it appears in the navigation.

Step 7: Preview and Check Everything Works

With the local server still running, check the following in your browser:

•      Every endpoint from your API appears, grouped correctly by tag

•      Clicking an endpoint shows its parameters, request body, and response format

•      The "Try it out" button sends a real request (this requires your API to be running and reachable)

•      Any endpoints that require login show a field for the access token

Step 8: Keep Docs Updated as the API Changes

The generated pages are a snapshot — editing the API doesn't update them automatically. Whenever the spec changes, re-run the two generation commands. To make this a single step, add a shortcut to package.json:

"scripts": {

"docs:api": "docusaurus gen-api-docs shopcore && docusaurus gen-api-docs:sidebar"

}

From then on, updating your reference pages is just:

npm run docs:api

Step 9: Deploy the Site

Once you're happy with the local preview, build the production version of the site:

npm run build

This creates a build folder containing a complete, static website. Upload that folder to any static hosting provider — Netlify, Vercel, and GitHub Pages are common free options. If your API itself is hosted separately, keep the documentation site on its own hosting rather than serving it from the API — static hosting is simpler and loads faster.

Quick Recap

•      Docusaurus turns folders of Markdown into a documentation website

•      An OpenAPI spec is the single file describing every endpoint

•      The OpenAPI plugin turns that spec into reference pages automatically

•      Hand-written guides live alongside the generated pages, not inside them

•      Re-run the generation command any time the spec changes

•      npm run build produces the files you actually deploy

From here, the main ongoing work is keeping the OpenAPI spec accurate and adding guides as questions come up from real users of the API.