Use tags for selective endpoints in docs.json

[jeremynovey]

We have large JSON files for our APIs (some with over 200 endpoints) and want to have an intro page for each endpoint category with matching endpoints listed below that page in the side nav.

Example:

Job Launcher

• Intro page with details and examples
• POST /launcher
• GET /launcher/status
• etc.

Current solutions in the docs are not ideal:

• Dedicated API sections: Add openapi field in docs.json with no other pages. All endpoints are included.
  • CONS: No intro page. All endpoints are included.
• Selective endpoints: Add specific endpoints in docs.json.
  • CONS: Not automated, so lots of work.
• Manually specify files: Create an MDX page for each endpoint.
  • CONS: Lots of work. Lots of extra files are created. Does not automatically update docs.json.
• Autogenerate MDX files: Use Mintlify scraper to autogenerate MDX pages.
  • CONS: Lots of work to keep docs.json updated. Lots of extra files. Does not automatically update docs.json (important when endpoints are added or removed).

FEATURE REQUEST: LIST ALL ENDPOINTS UNDER AN INTRO PAGE USING API "TAGS".

The problem I see is tags can have spaces, but since tags are arrays we can add something for Mintlify to pick up. As long as the first tag listed is the one we want, the others do not show up in a build. At least I could not get any extra tags to show in a browser. So we could add tags in kebob case to the JSON so tags": ["Job Configuration"] would become tags": ["Job Configuration","job-configuration"]. Then in docs.json it could look something like:

  "tab": "APIs",
  "groups": [
    {
      "group": "Job Launcher",
      "openapi": "api-reference/jobs.json",
      "pages": [
        "docs/apis/job-launcher",
        "mintlify-tag job-launcher"
      ]
    },
    {
      "group": "Job Configuration",
      "openapi": "api-reference/jobs.json",
      "pages": [
        "docs/apis/job-configuration",
        "mintlify-tag job-configuration"
      ]
    },
   etc.

I don't know what you use to parse docs.json. Here is an example using jq with the above Job Launcher "openapi" for the JSON path and "mintlify-tag" for the tag value:

jq -r '.paths| to_entries[]| .key as $path| .value| to_entries[]| select(.value.tags[]? == "job-launcher")| "\(.key | ascii_upcase) \($path)"' api-reference/jobs.json

Which would return:

POST /launcher
GET /launcher/status
POST /launcher/status
GET /launcher/status/{id}
GET /launcher/status/{id}/all
GET /launcher/driver/log/{jobId}
DELETE /launcher/{id}

This looks like what is already used for other methods. Seems easy enough to take from here.