⚡ Quick Reference

Commands Cheat Sheet

🚀 Main Commands

# Start development server
yarn start

# Update all API documentation
yarn docs:update

# Clean + update + build production
yarn docs:rebuild

# Build production
yarn build

📥 Swagger Management

# Fetch swagger from all services in .env
yarn swagger:fetch

# Enhance swagger files (add host, basePath, security)
yarn swagger:enhance

# Fetch + enhance (all-in-one)
yarn swagger:update

📚 Documentation Generation

# Generate docs for all APIs
yarn gen-all-docs

# Generate docs for specific API
yarn gen-api-docs <api-name>

# Example:
yarn gen-api-docs auth
yarn gen-api-docs rewards

🧹 Cleaning

# Clean all API docs
yarn clean-all-docs

# Clean specific API docs
yarn clean-api-docs <api-name>

# Clear Docusaurus cache
yarn clear

# Clear everything (cache + node_modules cache)
rm -rf .docusaurus node_modules/.cache

🔧 Sidebar & Tags

# Fix sidebars + generate tag pages
yarn sidebar:fix

---

File Structure

nomion-docs/
├── .env                          # ⚙️ Service configurations (GITIGNORED)
├── .env.example                  # 📝 Template for .env
├── examples/                     # 📄 Swagger JSON files
│   ├── auth.swagger.json
│   ├── rewards.swagger.json
│   └── statistic.swagger.json
├── docs/
│   ├── api/                      # 📚 Auto-generated API docs
│   │   ├── auth/
│   │   ├── rewards/
│   │   └── statistic/
│   └── guides/                   # 📖 Manual documentation
│       ├── add-new-service.md
│       └── quick-reference.md
├── scripts/                      # 🛠️ TypeScript utilities
│   ├── swagger-manager.ts        # Fetch & enhance swagger
│   └── sidebar-manager.ts        # Fix sidebars & tag pages
└── api-config.ts                 # 🎯 Auto-detect APIs from examples/

---

Environment Variables Format

# Template for each service
{SERVICE_NAME}_SWAGGER_JSON_URL=https://...
USERNAME_{SERVICE_NAME}=admin
PASSWORD_{SERVICE_NAME}=password
{SERVICE_NAME}_BASE_PATH=/path       # Optional
{SERVICE_NAME}_LABEL=Display Name    # Optional

Example:

AUTH_SWAGGER_JSON_URL=https://backend-dev.nomion.io/auth/swagger/json
USERNAME_AUTH=admin
PASSWORD_AUTH=secret123
AUTH_BASE_PATH=/auth
AUTH_LABEL=Authentication API

---

Common Workflows

🆕 Add New Service

# 1. Add to .env
echo "NEWSERVICE_SWAGGER_JSON_URL=https://..." >> .env
echo "USERNAME_NEWSERVICE=admin" >> .env
echo "PASSWORD_NEWSERVICE=password" >> .env

# 2. Update docs
yarn docs:update

# 3. Start server
yarn start

🔄 Update Existing Service

# Fetch latest swagger
yarn swagger:fetch

# Regenerate docs
yarn docs:update

🧹 Full Rebuild

# Clean everything and rebuild
yarn docs:rebuild

# Or manual steps:
yarn clean-all-docs
yarn clear
yarn docs:update
yarn build

🐛 Fix Issues

# Clear cache
yarn clear

# Regenerate specific API
yarn clean-api-docs auth
yarn gen-api-docs auth

# Hard reset
rm -rf .docusaurus node_modules/.cache
yarn start

---

API Testing

🔑 Bearer Token Format

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Important: Must include "Bearer " prefix with a space!

📍 API Endpoints

Format: https://{host}{basePath}{path}

Example:

• Host: backend-dev.nomion.io
• BasePath: /reward
• Path: /v1/admin/user-rewards
• Full URL: https://backend-dev.nomion.io/reward/v1/admin/user-rewards

---

Git Workflow

📝 Before Commit

# Make sure .env is gitignored
echo ".env" >> .gitignore

# Check what will be committed
git status

# Don't commit:
# - .env file
# - .docusaurus/ folder
# - node_modules/

✅ Safe to Commit

✅ examples/*.swagger.json
✅ docs/api/**/*.mdx
✅ .env.example
✅ scripts/*.ts
✅ package.json
✅ docusaurus.config.ts

---

Troubleshooting Quick Fixes

Issue	Quick Fix
API returns 404	Check basePath in swagger file
No Authorization button	Run yarn swagger:enhance
Chunk loading error	Run yarn clear && yarn start
Navbar not showing service	Restart dev server
Bearer token not working	Add "Bearer " prefix with space
CORS error	Backend must enable CORS headers

---

Performance Tips

⚡ Faster Development

# Only regenerate specific API instead of all
yarn gen-api-docs auth

# Skip sidebar fix if not needed
yarn swagger:update && yarn gen-all-docs

# Use --no-minify for faster builds
yarn build --no-minify

💾 Reduce Build Size

• Clean unused API docs
• Remove old swagger files from examples/
• Clear .docusaurus/ regularly

---

Keyboard Shortcuts (in docs)

Shortcut	Action
/	Focus search
s	Focus search
Ctrl+K	Command palette (if enabled)

---

Useful URLs

Development:    http://localhost:3000
API Explorer:   http://localhost:3000/docs/api/{service}/
Search:         http://localhost:3000/search

---

Support

• 📖 Full Guide: See add-new-service.md
• 🐛 Issues: GitHub Issues
• 💬 Discord: Nomion Community

---

Last Updated: November 2025

Add New Service (2 Steps)

1. Add to .env

{SERVICE_NAME}_SWAGGER_JSON_URL=https://your-api.com/swagger.json
USERNAME_{SERVICE_NAME}=admin
PASSWORD_{SERVICE_NAME}=password

2. Run Update

yarn docs:update

Done! ✨

Common Commands

Command	Description
yarn docs:update	Main command - Fetch & generate all docs
yarn swagger:fetch	Fetch Swagger files from URLs in .env
yarn gen-all-docs	Generate docs from existing Swagger files
yarn start	Start dev server
yarn build	Build for production
yarn clear	Clear cache

Environment Variables Format

# Required
{SERVICE_NAME}_SWAGGER_JSON_URL=https://...

# Optional (if endpoint requires auth)
USERNAME_{SERVICE_NAME}=admin
PASSWORD_{SERVICE_NAME}=secret

Examples:

AUTH_SWAGGER_JSON_URL=https://auth.api.com/swagger.json
PAYMENT_SWAGGER_JSON_URL=https://payment.api.com/swagger.json
NOTIFICATION_SWAGGER_JSON_URL=https://notify.api.com/swagger.json

Auto-Generated Structure

{SERVICE_NAME} → service-name
                ↓
examples/service-name.swagger.json
                ↓
docs/api/service-name/
                ↓
/docs/api/service-name/service-name-api

Custom Service Label

Edit api-config.ts:

const specialCases: Record<string, string> = {
  'auth': 'Auth',
  'payment': 'Payment',  // Add here
};

Troubleshooting

Service not showing?

yarn clear
yarn docs:update
yarn start

Fetch failed?

• ✅ Check URL is accessible
• ✅ Verify username/password if required
• ✅ Check .env file syntax
• ✅ Ensure HTTPS endpoint allows self-signed certs

Build errors?

yarn clean-all-docs
yarn clear
yarn docs:update

Full Update Pipeline

yarn docs:update runs:

1. fetch-swagger - Fetch from URLs
2. enhance-swagger - Add metadata
3. fix-swagger - Fix security schemes
4. fix-swagger-operations - Normalize IDs
5. gen-api-docs all - Generate docs
6. generate-tag-pages - Create tag pages
7. fix-sidebars - Fix navigation

New Feature: Curl Debug Tab

After sending any API request, a Curl tab appears showing the exact curl command for debugging! 🎉

curl --location 'https://api.example.com/v1/users' \
--header 'Authorization: Bearer xxx' \
--header 'Content-Type: application/json' \
--data '{"name":"John"}'

Perfect for:

• 📋 Copy-paste to terminal
• 🐛 Debug requests
• 📝 Share with team
• 🔧 Test in Postman/Insomnia