Using the API Plugin

The pan.dev site now uses docusaurus-openapi-docs plugin to generate markdown files from OpenAPI Spec files. If you want to get a more in depth understanding of the plugin, refer to this readme

CLI

The plugin utilizes a list of cli commands to generate and clean the API documentation from the directory. These scripts are meant to run before starting or building the site. For that reason, we have included the generation within the yarn start and yarn build commands.

Configuration

The plugin has a configuration within docusaurus.config.js.

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 above example 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), you should add an entry to this configuration. At a minimum, each API needs to specify

specPath is used to denote the directory that your OpenAPI Specification is in. This needs to be unique for each API. This should follow the pattern of openapi-specs/<product>/<api-name-if-needed>
outputDir is the directory the markdown files will be written out to. This needs to be unique for each API. This should 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.js that groups the operations by their tag. Ensure that the tags are defined globally. To use this options you can add the follow options to the APIs config.

sidebarOptions: {
    groupPathsBy: "tag"
}

You will then need to add this sidebar array in the products/<product>/sidebars.js 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.js
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 the products/product/sidebars.js to know to autogenerate the sidebar for the API Directory.

products/<product>/sidebars.js
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. If you add a new versioned API, you might need to make updates to the package.json to ensure the commands yarn clean-all and yarn gen-all work.

to the gen-all command add && docusaurus gen-api-docs:version \<id\>:all to the end, similar to the insights.
to the clean-all command add && docusaurus clean-api-docs:version \<id\>:all to the end, similar to the insights.

Example of APIs to reference

There are 4 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 the docusaurus.config.js
sidebars.js in products/dns-security/sidebars.js

Single Spec, No tags, One API, One Version

See iot. Note the following:

lack of sidebarOptions in the docusaurus.config.js
autogenerated sidebar in products/iot/sidebars.js

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 it's own configuration in docusaurus.config.js with sidebarOptions
Each API has it's own sidebar in products/sase/sidebars.js

An API with Multiple Versions

See access/api/insights. Note the following:

More complex configuration in docusaurus.config.js with version, label, baseUrl, and versions object
products/access/sidebars.js has insightVersions (name this for your product)
Require of versionSelect and versionCrumb in products/access/sidebars.js. You will need to copy these lines.
saseinsightsv1/saseinsightsv2 sidebars in products/access/sidebars.js.
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 the products/ directory, you will need to create one with a sidebars.js 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. To do this you can run a yarn clean-api-docs <id> where the ID is the key of the APIs configuration in docusaurus.config.js. i.e. for iot you would run yarn clean-api-docs iot. The command is slightly different for versioned docs, see the docs.. After cleaning you can generate the new docs with the 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. Else, 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 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.js is using the correct docIDs and referecing the right API sidebar.
For other issues, try to run a yarn sos to clean up the project before running yarn start
If these 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 of APIs to reference​

FAQs​

CLI