Using the API Plugin

The pan.dev site uses the docusaurus-openapi-docs plugin to generate Markdown files from OpenAPI Spec files. For a deeper dive, refer to the plugin README.

CLI

The plugin exposes a set of CLI commands that generate and clean the API documentation directory. These scripts are meant to run before starting or building the site, so we've wired the generation into the yarn start and yarn build commands.

Configuration

The plugin has a configuration entry in docusaurus.config.ts.

See an example configuration

[
  "docusaurus-plugin-openapi-docs",
  {
    id: "default",
    docsPluginId: "default",
    config: {
      auth: {
        specPath: "openapi-specs/sase/auth",
        outputDir: "products/sase/api/auth",
        sidebarOptions: {
          groupPathsBy: "tag",
        },
      },
      iam: {
        specPath: "openapi-specs/sase/iam",
        outputDir: "products/sase/api/iam",
        sidebarOptions: {
          groupPathsBy: "tag",
          categoryLinkSource: "info",
        },
      },
      insights: {
        specPath: "openapi-specs/access/insights/2.0",
        outputDir: "products/access/api/insights",
        sidebarOptions: { groupPathsBy: "tag" },
        version: "2.0",
        label: "v2.0",
        baseUrl: "/access/api/insights/",
        versions: {
          "1.0": {
            specPath: "openapi-specs/access/insights/1.0",
            outputDir: "products/access/api/insights/1.0",
            label: "v1.0",
            baseUrl: "/access/api/insights/1.0/",
          },
        },
      },
    },
  },
]

For each API we have a configuration. In the example above, auth, iam, and insights are the API IDs. For each separate API Doc section (i.e. if you want the API to have its own sidebar), add an entry to this configuration.

At a minimum, each API needs to specify:

specPath — the directory that contains your OpenAPI Specification. Must be unique for each API. Follow the pattern openapi-specs/<product>/<api-name-if-needed>.
outputDir — the directory the Markdown files will be written to. Must be unique for each API. Follow the pattern products/<product>/api/<api-name-if-needed>.

You will likely also need to use sidebarOptions based on how your OpenAPI Spec is set up.

Sidebars for APIs that use tagging

If you use tags on all your operations, the plugin will create a sidebar.ts that groups the operations by their tag. Ensure that the tags are defined globally. To use this option, add the following options to the API's config:

sidebarOptions: {
    groupPathsBy: "tag"
}

You will then need to add this sidebar array in the products/<product>/sidebars.ts file. You can also include any docs you want to show up in the API Sidebar by including their docIds in the sidebar.

products/<product>/sidebars.ts
module.exports = {
  "<product-name>-api": [
    "doc-1",
    "doc-2", // All docs you want to include before go here
    require("./api/<product>/<api-name-if-needed>/sidebar"),
  ],
  "<product-name>-docs": [
    // Docs Sidebar goes here
  ],
};

Sidebars for APIs that don't use tagging

If you don't use tags, you can use the autogenerated sidebars feature. For this option you need to add a _category_.json like the one below:

products/<product>/api/<api-name-if-needed>/_category_.json
{
  "label": "Sidebar Category Name",
  "collapsible": true,
  "link": {
    "type": "generated-index",
    "title": " Sidebar Category Name"
  }
}

You then need to edit products/<product>/sidebars.ts so it autogenerates the sidebar for the API directory.

products/<product>/sidebars.ts
module.exports = {
  "<product-name>-api": [
    {
      type: "autogenerated",
      dirName: "./api", // generate sidebar from the api folder
    },
  ],
  "<product-name>-docs": [
    // Docs Sidebar goes here
  ],
};

APIs with versions

Visit the plugin docs for information on versioned APIs. The repo's gen-all and clean-all scripts already pass --all-versions, so newly added versioned APIs are picked up automatically — no package.json edits required.

Example APIs to reference

There are four variables to consider when deciding how to configure your API:

Single or multiple spec files
Uses tags or doesn't use tags

Note: If you have multiple specs you must use tags or create a separate config for each spec file.
One API for the product or multiple APIs for the product
One version or multiple versions of the API

Single spec, uses tags, one API, one version

See dns-security. Note the following:

sidebarOptions in docusaurus.config.ts
products/dns-security/sidebars.ts

Single spec, no tags, one API, one version

See iot. Note the following:

Lack of sidebarOptions in docusaurus.config.ts
Autogenerated sidebar in products/iot/sidebars.ts

Multiple specs, uses tags, multiple APIs

See sase, which consists of auth, iam, mt-monitor, subscription, and tenancy APIs. Note the following:

Each API has its own configuration in docusaurus.config.ts with sidebarOptions
Each API has its own sidebar in products/sase/sidebars.ts

An API with multiple versions

See access/api/insights. Note the following:

More complex configuration in docusaurus.config.ts with version, label, baseUrl, and versions object
products/access/sidebars.ts has insightVersions (name this for your product)
Require of versionSelect and versionCrumb in products/access/sidebars.ts. You will need to copy these lines.
saseinsightsv1 / saseinsightsv2 sidebars in products/access/sidebars.ts
You can also visit the plugin docs for more information on versioned APIs

FAQs

I want to add a new API, is there anything special I need to do?

If your product doesn't already have a directory in products/, create one with a sidebars.ts file and a folder for api inside of it. See the above examples for ideas of how to get started.

How are the URLs created for each endpoint?

The URLs are the path of the API directory (minus products/) plus the operationID in kebab-case.

I updated my spec file, do I need to do anything?

Yes. After updating the spec file, you need to clean the existing API Docs. Run yarn clean-api-docs <id>, where the ID is the key of the APIs configuration in docusaurus.config.ts. For example, for iot you would run yarn clean-api-docs iot. The command is slightly different for versioned docs; see the docs. After cleaning, generate the new docs with yarn gen-api-docs <id>.

Things don't seem to be working

Issues running yarn gen-api-docs <id> or yarn gen-all

There is potentially a problem with your OpenAPI Spec file. Please make sure it is valid. We recommend using Spectral within VSCode to spot any issues. Otherwise, make sure the configuration of your API Doc is referencing the right paths.

Issues running yarn start or yarn build

If you see a long list of paths one line at a time (e.g. threat-vault/docs/response-fields/threat-vault-response), it's most likely an issue with your sidebar. Make sure your sidebars.ts is using the correct docIDs and referencing the right API sidebar.
For other issues, try running yarn sos to clean up the project before running yarn start.
If those don't work, contact us in #pan-dev on Slack and provide the output of running a yarn sos && yarn start command.

CLI​

Configuration​

Sidebars for APIs that use tagging​

Sidebars for APIs that don't use tagging​

APIs with versions​

Example APIs to reference​

Single spec, uses tags, one API, one version​

Single spec, no tags, one API, one version​

Multiple specs, uses tags, multiple APIs​

An API with multiple versions​

FAQs​

CLI