Setting Up Mintlify for API Documentation: A Beginner's Guide
Mintlify is an excellent tool for creating API documentation with ease. This guide walks you through the entire setup process, from creating an account to successfully running Mintlify with OpenAPI integration.
I wrote this guide from a beginner's perspective, having searched for a simple guide for a complete beginner and not found one. This guide includes errors you'd likely encounter and how to solve them.
Prerequisite: Install VS Code. If you have that installed, we're good to go.
1. Creating a Mintlify Account
Go to Mintlify.
Sign up using your GitHub or Google account.
Once logged in, navigate to the "Get Started" section to access the starter templates.
2. Cloning and Forking the Mintlify Starter Template
1. Visit the Mintlify GitHub repository.
2. Fork the repository to your GitHub account.
3. Clone it to your local machine by typing the following code into your terminal on VS Code.
|
4. Navigate into the project folder by typing the following commands into your terminal.
|
3. Referencing openapi.yaml in docs.json
Note: mint.json was recently replaced by docs.json. This means you should be searching for docs.json on the cloned folder in your computer, and not mint.json. You should find it in the Starter directory.
1. Open docs.json in any code editor. I recommend VS Code.
2. Add the OpenAPI reference inside docs.json.Your code should look like the one below.
|
3. Save the file.
This tells Mintlify where to find the OpenAPI spec and how to integrate it into your documentation.
4. Installing Git and Node.js
Mintlify requires Git and Node.js. If you haven’t installed them:
Git: Download here
Node.js: Download here
Verify installation by typing the following commands into your command line for each installation.
|
|
5. Running npx Command & Troubleshooting Errors
Initial Command:
After ensuring your OpenAPI file is correctly referenced, run the following command:
npx @mintlify/scraping@latest openapi-file ./openapi.yaml
Common Errors & Fixes
If you encounter an error similar to: "Running scripts is disabled on this system", here's the solution.
Open PowerShell terminal on VS Code as Administrator and run the following commands.
|
Then, retry the command.
If you encounter an error with a message similar to: "ENOENT: no such file or directory, open 'C:\Users\Samuel\Desktop\Mintlify\openapi.yaml'", consider the solution below.
Ensure the correct path is used. If openapi.yaml is inside api-reference, run the following commands.
|
6. Running npx mintlify dev
Once the OpenAPI file is populated, start the Mintlify local server:
|
Common Errors & Fixes
If you encounter an error with a message similar to: "Must be run in a directory where a mint.json or docs.json file exists", consider the following options.
- Check if docs.json exists in the current directory by typing the command below.
|
- If missing, navigate to the correct folder by typing the command below.
|
- Try running the command again
|
Security Risks of Unrestricted Execution Policy
1. Runs Any Script Without Confirmation
Any PowerShell script, including potentially harmful ones, can run without warning.
2. Increases Malware and Phishing Risks
Malicious scripts disguised as legitimate ones can execute without user approval.
3. No Digital Signature Checks
Unlike RemoteSigned or AllSigned, Unrestricted mode does not verify script authenticity.
4. Can Be Used for Privilege Escalation
Attackers can exploit this setting to execute scripts that modify system settings or install malicious software.
Safer Alternatives
Instead of Unrestricted, consider using any of the following.
1. RemoteSigned
Allows locally created scripts but requires signed scripts from the internet.
|
2. Bypass (Temporary)
Ignores policy only for the current session.
|
After running your required scripts, always reset the policy using the following commands.
|
If all steps are followed correctly, your Mintlify documentation should now be running successfully! Congratulations! You’ve now set up Mintlify for API documentation. If you're stuck, drop your questions in the comments and I'll give you the support you need.