Neko Defense API Documentation Portal

Centralized OpenAPI/Swagger documentation aggregation for all Neko Defense System microservices

Nyaa~! Welcome to the unified API documentation portal, desu! 🐾📚

Overview

The Neko Defense API Documentation Portal is a professional NestJS microservice that aggregates and displays OpenAPI/Swagger documentation from all Neko Defense System microservices in a single, unified interface.

Key Features

• Multi-Service Aggregation: Automatically fetches and displays documentation from 5 microservices
• Real-Time Health Monitoring: Live status tracking for all registered services
• Smart Caching: Reduces load on services with configurable TTL (default: 5 minutes)
• RULE 57 Compliant: Comprehensive audit logging for all documentation access
• Beautiful Swagger UI: Enhanced interface with custom styling
• Search Functionality: Search across all API endpoints
• MongoDB Atlas Integration: RULE 47 compliant (Atlas only, never localhost)
• Docker Support: Multi-stage Alpine-based containerization
• TypeScript: Fully type-safe codebase (RULE 16)

Architecture

This service follows RULE 5 (Microservices Architecture):

src/
├── app.module.ts                      # Root module (orchestration)
├── main.ts                            # Entry point with Swagger setup
├── docs/
│   ├── docs.module.ts                 # Documentation module (orchestration ONLY)
│   ├── docs.controller.ts             # API endpoints
│   ├── docs.service.ts                # Service (external interactions)
│   ├── dto/service-config.dto.ts      # Validation (non-blocking)
│   └── interfaces/openapi-spec.interface.ts
├── schemas/
│   ├── audit-log.schema.ts            # RULE 57 audit logging
│   └── service-registry.schema.ts     # Service registration
├── common/
│   └── interceptors/
│       └── audit-log.interceptor.ts   # Global audit logging
└── health/
    ├── health.controller.ts           # Health check endpoint
    └── health.module.ts

Aggregated Microservices

| Service | Port | Description | OpenAPI Path | |---------|------|-------------|--------------| | Authentication Service | 3003 | Authentication & Authorization | /api-json | | API Gateway | 3100 | Unified API Gateway | /api-json | | Chilean Law RAG | 3001 | Legal Document Retrieval | /api-json | | Forensic Intelligence | 3002 | Threat Actor Analysis | /api-json | | Video Frame Generator | 3000 | Frame Generation | /api-json |

Quick Start

Prerequisites

• Node.js 18+
• MongoDB Atlas account (RULE 47)
• All microservices running (optional, but recommended)

Installation

# Clone repository
cd /home/wakibaka/Documents/github/neko-defense-api-docs

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Edit .env with your MongoDB Atlas URI and service URLs
nano .env

Configuration

Edit .env file:

# Server Configuration
PORT=3200
NODE_ENV=development
SERVICE_NAME=neko-defense-api-docs

# MongoDB Atlas Connection (RULE 47 - Atlas only!)
MONGODB_URI=mongodb+srv://username:[email protected]/neko-defense-system

# Microservice URLs
AUTH_SERVICE_URL=http://localhost:3003
GATEWAY_SERVICE_URL=http://localhost:3100
RAG_SERVICE_URL=http://localhost:3001
FORENSIC_SERVICE_URL=http://localhost:3002
VIDEO_SERVICE_URL=http://localhost:3000

# Caching Configuration
SPEC_CACHE_TTL_SECONDS=300
SERVICE_HEALTH_TIMEOUT_MS=5000

# Audit Logging (RULE 57)
ENABLE_AUDIT_LOGGING=true
AUDIT_LOG_RETENTION_DAYS=90

Development

# Start in development mode
npm run start:dev

# Start in watch mode
npm run start:watch

# Build for production
npm run build

# Start production server
npm run start:prod

Docker Deployment

# Build Docker image
docker build -t neko-defense-api-docs .

# Run with docker-compose
docker-compose up -d

# Check logs
docker-compose logs -f api-docs

# Stop service
docker-compose down

API Endpoints

Documentation Portal

• GET / - Welcome message with service list
• GET /docs - Swagger UI (main documentation interface)
• GET /health - Health check endpoint

Service Management

• GET /api/services - List all registered services with status
• GET /api/services/:serviceName/spec - Get OpenAPI spec for specific service
• GET /api/services/:serviceName/health - Check health of specific service
• GET /api/services/merged-spec - Get merged OpenAPI spec (all services)
• POST /api/services/refresh - Force refresh all OpenAPI specifications

Example Usage

# Check service health
curl http://localhost:3200/health

# Get all services
curl http://localhost:3200/api/services

# Get auth service spec
curl http://localhost:3200/api/services/auth-service/spec

# Check auth service health
curl http://localhost:3200/api/services/auth-service/health

# Force refresh all specs
curl -X POST http://localhost:3200/api/services/refresh

# Access Swagger UI
open http://localhost:3200/docs

MongoDB Collections

Database: neko-defense-system

service-registry

Stores registered microservices and their OpenAPI specifications.

Schema:

{
  name: string;              // Unique service identifier
  displayName: string;       // Human-readable name
  url: string;               // Base URL
  description: string;       // Service description
  openApiPath: string;       // OpenAPI spec path
  openApiSpec: object;       // Cached OpenAPI spec
  status: 'online' | 'offline' | 'unknown';
  version: string;           // Service version
  lastChecked: Date;         // Last health check
  lastSuccessfulFetch: Date; // Last successful spec fetch
  fetchAttempts: number;     // Total fetch attempts
  failedAttempts: number;    // Failed attempts count
  lastError: string;         // Last error message
  metadata: object;          // Additional metadata
}

api-docs-audit-logs

RULE 57 compliant audit logging for documentation access.

Schema:

{
  timestamp: Date;           // Event timestamp
  eventType: string;         // 'access' | 'refresh' | 'health_check' | 'spec_fetch' | 'error'
  serviceName: string;       // Target service
  endpoint: string;          // Request endpoint
  method: string;            // HTTP method
  statusCode: number;        // Response status
  ipAddress: string;         // Client IP
  userAgent: string;         // User agent
  requestHeaders: object;    // Sanitized headers
  requestQuery: object;      // Query parameters
  responseTime: number;      // Response time (ms)
  errorMessage: string;      // Error message if any
  metadata: object;          // Additional metadata
  isSecurityEvent: boolean;  // Security-related flag
  sessionId: string;         // Session tracking ID
}

TTL Index: Automatic cleanup after 90 days (RULE 57)

Adding New Services

To register a new microservice:

1. Add to environment variables (.env):

NEW_SERVICE_URL=http://localhost:3004

2. Update DocsService (src/docs/docs.service.ts):

{
  name: 'new-service',
  displayName: 'New Service Name',
  url: this.configService.get<string>('NEW_SERVICE_URL'),
  description: 'Service description',
  openApiPath: '/api-json',
}

3. Restart the service:

npm run start:dev

The new service will be automatically registered in MongoDB and monitored.

Caching Strategy

• Default TTL: 5 minutes (300 seconds)
• Cache Location: MongoDB service-registry collection
• Cache Invalidation: Automatic on TTL expiry or manual via /api/services/refresh
• Benefits: Reduces load on microservices, faster response times

RULE 57 Audit Logging

All requests are logged to MongoDB with the following information:

• Event Type: access, refresh, health_check, spec_fetch, error
• Request Details: IP, User-Agent, headers (sanitized), query params
• Response Details: Status code, response time
• Security Events: Flagged for unauthorized/forbidden errors
• Retention: 90 days (automatic cleanup via TTL index)

Query audit logs:

# Using MongoDB Compass or MCP
use neko-defense-system
db['api-docs-audit-logs'].find({ eventType: 'access' }).sort({ timestamp: -1 }).limit(10)

Troubleshooting

Service Shows Offline

1. Check service is running:

curl http://localhost:3003/health

2. Check service URL in .env:

echo $AUTH_SERVICE_URL

3. Force refresh specs:

curl -X POST http://localhost:3200/api/services/refresh

MongoDB Connection Issues

1. Verify Atlas URI (RULE 47 - NEVER use localhost):

# WRONG
MONGODB_URI=mongodb://localhost:27017

# CORRECT
MONGODB_URI=mongodb+srv://...

2. Check network access in MongoDB Atlas

3. Verify credentials

OpenAPI Spec Not Loading

1. Check service has Swagger enabled
2. Verify OpenAPI path (default: /api-json)
3. Check logs:

docker-compose logs -f api-docs

Development Guidelines

RULE 5 Compliance

• Modules: Orchestration ONLY
• Services: External interactions (HTTP, MongoDB)
• Controllers: API endpoints
• DTOs: Non-blocking validation

RULE 16 (TypeScript)

All code is TypeScript with strict type checking.

RULE 47 (MongoDB Atlas)

NEVER use localhost:27017 - Always MongoDB Atlas URIs.

RULE 57 (Audit Logging)

All requests automatically logged via global interceptor.

Testing

# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Test coverage
npm run test:cov

NPM Publishing

This package can be published to NPM (RULE 48 compliant):

# Audit for credentials
grep -r "MONGODB_URI\|API_KEY\|SECRET" src/

# Build
npm run build

# Test package
npm pack
npm install ./neko-arc-defense-api-docs-1.0.0.tgz

# Publish (pre-authenticated as lanitamarihuanera)
npm publish --access public

Performance Optimization

• Caching: 5-minute TTL reduces API calls
• Connection Pooling: MongoDB connection reuse
• Alpine Linux: Small Docker image (~50MB)
• Health Checks: Automatic service monitoring
• Indexes: Optimized MongoDB queries

Security

• Non-root Docker User: Runs as nekoarc:1001
• Header Sanitization: Sensitive headers redacted in logs
• CORS Enabled: Configured for browser access
• Audit Logging: RULE 57 compliant comprehensive logging
• Environment Variables: No hardcoded credentials

License

MIT

Contributing

This is part of the Neko Defense System. All contributions follow the six-personality collaboration model:

• 🐾 Neko-Arc: Technical execution
• 🎭 Mario: Automation orchestration
• 🗡️ Noel: Debugging and testing
• 🎸 Glam: Documentation (Spanish)
• 🧠 Hannibal: Forensic analysis
• 🧠 Tetora: Multi-perspective review

Support

For issues or questions:

1. Check logs: docker-compose logs -f api-docs
2. Verify configuration: .env file
3. Check service health: curl http://localhost:3200/health
4. Review audit logs in MongoDB

Nyaa~! Happy documenting, desu! 🐾📚✨