API Documentation Automation

Overview

This setup automatically generates API documentation from swagger.yaml and injects custom content without modifying the swagger file or backend code.

Workflow

1. Update Swagger File

When you pull a new swagger.yaml from your backend repo, simply replace the file at the root of this project.

2. Regenerate API Documentation

Run the following command to regenerate API docs with custom content:

npm run gen-api-docs

This command does two things:

1. Generates fresh API documentation from swagger.yaml
2. Automatically injects custom content (like encryption guides)

3. Custom Content

Custom content that needs to be added to specific API endpoints is stored in docs/api-custom/:

docs/api-custom/
  ├── upload-kyc-details.md    # Custom encryption guide for KYC upload
  └── [other-api-name].md      # Add more custom content files as needed

4. Sidebar Auto-Generation

The API sidebar is automatically generated based on the tags in your swagger.yaml file. When new endpoints are added:

• They automatically appear in the sidebar
• They're organized by their tags
• No manual sidebar configuration needed

Adding Custom Content for New APIs

To add custom documentation for any API endpoint:

1. Create a new file in docs/api-custom/:

   docs/api-custom/my-new-api.md

2. Add your custom content (code examples, notes, etc.)

3. Update scripts/inject-custom-content.js to map your custom file:

   const injections = [
     {
       customFile: 'upload-kyc-details.md',
       targetFile: 'upload-kyc-details.api.mdx',
       insertAfter: 'Submit KYC documents and information for user verification',
     },
     {
       customFile: 'my-new-api.md',
       targetFile: 'my-new-api.api.mdx',
       insertAfter: 'Description text from swagger',
     },
   ];

4. Run npm run gen-api-docs

Full Automation Workflow

For CI/CD or automated updates:

# 1. Pull latest swagger.yaml from backend repo
git pull origin main swagger.yaml

# 2. Regenerate docs with custom content
npm run gen-api-docs

# 3. Deploy (if using automated deployment)
npm run build

File Structure

onmeta-docs/
├── swagger.yaml                   # Source API specification (auto-pulled from backend)
├── docs/
│   ├── api/                      # Generated API docs (auto-generated, don't edit)
│   │   ├── *.api.mdx            # Individual API endpoint pages
│   │   └── sidebar.ts           # Auto-generated sidebar
│   └── api-custom/               # Custom content to inject (version controlled)
│       └── upload-kyc-details.md
├── scripts/
│   └── inject-custom-content.js  # Injection script
└── docusaurus.config.ts          # Docusaurus configuration

Benefits

✅ Separation of Concerns: Custom docs are separate from swagger.yaml ✅ No Backend Changes: Backend devs don't need to maintain documentation code ✅ Automatic Updates: New APIs automatically appear when swagger is updated ✅ Persistent Customization: Custom content survives swagger.yaml updates ✅ Version Controlled: All customizations are in git