ManageXR API docs via Mintlify

Learn how to set up the ManageXR public API documentation repo on your machine and best practices for updating our external API docs.

Getting Started

Install the Mintlify CLI to preview the documentation changes locally. Use the same level of Node as the mighty-api repo (e.g., 20.11.1). To install mintlify tools, use the following command

npm i -g mintlify

Run the following command at the root of your documentation (where mint.json is)

mintlify dev

To view it on a port other than 3000, use a flag e.g.,

mintlify dev --port 3333

Troubleshooting

• Mintlify dev isn't running - Run mintlify install it'll re-install dependencies.
• Page loads as a 404 - Make sure you are running in a folder with mint.json

Adding Endpoints to the Api-Reference

The API Reference contains all of the information about the ManageXR Public API. To add a new endpoint, make the following changes:

1. Update openapi.yaml to include info about the endpoint. Format according to OpenAPI 3.1.0 specifications.
2. Create an mdx file within api-reference>endpoint. Include a title and an openapi url. See existing examples in the directory. It is important that the openapi url matches the openapi.yaml specification for the endpoint. Mintlify also has options to generate these automatically.
3. Update mint.json to include the endpoint mdx page in the documentation. Put the file in the appropriate group e.g., if it is an endpoint for devices, put it in the "Devices" group. If it is an endpoint for a group that does not exist, create a group. Eventually, we will have groups for Devices, Organizations, Configurations, Library (will include VR Content, Files, Wifi), Users etc.

Save and run the mintlify repo locally to validate changes.

Reviewing & Publishing Changes

Changes are deployed automatically to docs.managexr.com once merged into the main branch.

• Submit a PR for doc changes along with your API PR
• Do not merge doc changes until after API release

Tips and Tricks

• Search Mintlify help docs
• The essentials directory contains helpful examples of markdown in action
• To use mutliple lines in an OpenAPI description, use the | character. CMD+F | in openapi.yaml for examples.
• Not sure how to format? Look for existing examples in openapi.yaml. Otherwise, ask ChatGPT. It is pretty good at spitting out the correct openapi format or identifying whether a formatting option is possible.