Skip to main content

🚀 Add New Service

Overview​

Only 2 simple steps to add a new API service to the documentation:

  1. ✅ Add configuration to .env file
  2. ✅ Run 1 single command

Step 1: Configure in .env​

Open the .env file (if it doesn't exist, copy from .env.example) and add configuration for the new service:

# Replace YOURSERVICE with service name (e.g., AUTH, REWARDS, CORE)
YOURSERVICE_SWAGGER_JSON_URL=https://backend-dev.nomion.io/yourservice/swagger/json
USERNAME_YOURSERVICE=admin
PASSWORD_YOURSERVICE=your-password
YOURSERVICE_BASE_PATH=/yourservice    # Optional - auto-detect from URL
YOURSERVICE_LABEL=Your Service API    # Optional - auto-generate from name

Real Example​

# Add Auth API
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

# Add Rewards API
REWARDS_SWAGGER_JSON_URL=https://backend-dev.nomion.io/reward/swagger/doc.json
USERNAME_REWARDS=admin
PASSWORD_REWARDS=nomion@123
REWARDS_BASE_PATH=/reward
REWARDS_LABEL=Rewards API

Step 2: Run Update Command​

yarn docs:update

Or if you want to clean everything and rebuild:

yarn docs:rebuild

System Automatically Performs​

When you run yarn docs:update, the system will automatically:

  1. ✅ Fetch swagger JSON from URL (with basic authentication)
  2. ✅ Enhance swagger file:
    • Set correct host, basePath, schemes
    • Remove endpoint-level security
    • Add global security (Bearer token)
    • Fix missing summary/operationId
  3. ✅ Generate complete API documentation
  4. ✅ Create tag overview pages for each API group
  5. ✅ Fix sidebar structure automatically
  6. ✅ Update navbar menu (auto-detect from examples/)

Result​

After completion, the new service will appear:

  • 📁 Swagger file: examples/yourservice.swagger.json
  • 📚 Docs folder: docs/api/yourservice/
  • 🔗 Navbar menu: Automatically added menu item
  • 🔒 Authentication: Full Bearer token support
  • 📖 Tag pages: Auto-created overview for each tag

View Result​

yarn start

Open browser and visit: http://localhost:3000

Troubleshooting​

❌ Error: "No swagger sources found in .env"​

Cause: .env file doesn't exist or has no service configuration

Solution:

  • Ensure .env file exists (copy from .env.example)
  • Check there's at least 1 service with format: {NAME}_SWAGGER_JSON_URL

❌ Error: "HTTP 401 Unauthorized" when fetching​

Cause: Incorrect username/password

Solution:

  • Check if USERNAME_{SERVICE} and PASSWORD_{SERVICE} are correct
  • Try logging into swagger URL via browser to verify

❌ API doesn't show Authorization button​

Cause: Swagger file hasn't been enhanced

Solution:

yarn swagger:enhance
yarn gen-all-docs

❌ API returns 404 when testing​

Cause: Incorrect basePath

Solution:

  • Check {SERVICE}_BASE_PATH in .env
  • Or leave empty to auto-detect from URL
  • Regenerate: yarn docs:rebuild

❌ Navbar doesn't show new service​

Cause: Cache or docs haven't been generated

Solution:

yarn clear
yarn start

Important Notes​

✅ Naming Convention​

  • Service name: Always use UPPERCASE (e.g., AUTH, not auth)
  • File output: Auto-lowercase (e.g., auth.swagger.json)
  • Docs folder: Auto-lowercase (e.g., docs/api/auth/)

✅ Bearer Token Format​

When testing API in docs, enter token with format:

Bearer your-token-here

Note: Must include "Bearer" prefix with a space before token!

✅ Base Path Detection​

If {SERVICE}_BASE_PATH is not set in .env, system will auto-extract from URL:

  • URL: https://backend-dev.nomion.io/auth/swagger/json
  • Auto basePath: /auth ✅

✅ Clean Cache​

If encountering strange errors, always try clearing cache first:

yarn clear
# Or
rm -rf .docusaurus node_modules/.cache

Commands Reference​

# Only fetch swagger files
yarn swagger:fetch

# Only enhance swagger files
yarn swagger:enhance

# Fetch + enhance
yarn swagger:update

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

# Clean all API docs
yarn clean-all-docs

# Fix sidebars + create tag pages
yarn sidebar:fix

# Update everything (recommended)
yarn docs:update

# Clean + update + build production
yarn docs:rebuild

Next Steps​

After successfully adding a new service:

  1. ✅ Check API docs in browser
  2. ✅ Test Authorization with Bearer token
  3. ✅ Test some endpoints
  4. ✅ Commit changes to Git (remember to .gitignore the .env file)

Made with ❤️ by Phygital Labs