Effortless API Documentation with Maira-CLI: Generate Swagger Docs on the Fly

rahman orewole — Fri, 28 Mar 2025 15:27:26 +0000

Documenting APIs is often tedious, but what if you could generate detailed Swagger documentation automatically while testing your API? That's exactly what Maira-CLI does. This developer tool intercepts requests and responses to create accurate API documentation without additional effort.
Getting Started with Maira-CLI
Step 1: Install Maira-CLI
First, install Maira-CLI globally on your system using npm:
npm install -g maira-cli
Step 2: Start the Proxy Server
Run the proxy inside the backend project you want to document. Replace values as needed:
maira-cli http --port=3000 --project=userDoc --baseurl=http://localhost:3000
--port=3000: The port your backend server is running on.
--project=userDoc: The name of the documentation folder.
--baseurl=http://localhost:3000: The base URL of your API.

Step 3: Configure Routes and Authentication
After running the command, Maira-CLI creates a folder: /maira_docs/userDoc/. Inside, you'll find:
config.json: Define project details, routes to document, and authentication headers.
paths.json: Stores detected API paths and request details.

Example config.json { "title": "User Documentation", "version": "1.0.0", "serverUrls": ["http://localhost:3000"], "routes": [ "/ping/pong", "/ping", "/ping/:id" ], "security": { "apiKey": ["x-api-key", "x-api-user"], "http": ["authorization"] } }
Once configured, make API requests through the proxy (http://localhost:8081) just as you would normally.
Step 4: Generating Documentation
Maira-CLI generates a swagger_template.json file based on config.json. After making requests, run:
maira-cli generate -c=./maira_docs/userDoc/swagger_template.json -p=./maira_docs/userDoc/paths.json -o=./maira_docs/userDoc/docs -n=user-docs.json
Step 5: Viewing Your Documentation
Once generation is complete, you'll receive a preview link, like:
https://maira-virid.vercel.app/?id=uuid
This link allows you to share and view your API documentation effortlessly.
Why Use Maira-CLI?
✅ No manual Swagger setup - Everything is automatically generated while you test your API. ✅ Captures request & response data - Ensures accurate documentation. ✅ Supports authentication headers - Securely documents API access methods. ✅ Easy preview & sharing - Get a hosted link to your generated docs.
Maira-CLI makes API documentation simple and efficient. Try it today! 🚀

DEV Community: rahman orewole

Effortless API Documentation with Maira-CLI: Generate Swagger Docs on the Fly