Fix API silent failures and add OpenAPI 3.0 spec with Swagger UI

[Copilot]

Problem

The Classification API had two critical usability issues that led to user confusion:

1. Silent Failures with Invalid task_type Values

Invalid task_type parameters silently defaulted to intent classification instead of returning an error:

# All of these returned HTTP 200 with INTENT classification results:
curl -X POST localhost:8080/api/v1/classify/batch \
  -d '{"texts":["test"], "task_type":"jailbreak"}'

curl -X POST localhost:8080/api/v1/classify/batch \
  -d '{"texts":["test"], "task_type":"invalid_type"}'

This caused real-world confusion when testing jailbreak detection - users assumed task_type: "jailbreak" would work, but it silently used intent classification instead. The correct parameter is task_type: "security".

2. No API Discoverability

There was no way to discover API capabilities without reading source code:

curl http://localhost:8080/docs          # 404
curl http://localhost:8080/openapi.json  # 404  
curl http://localhost:8080/api/v1        # 404

Solution

Input Validation

Added validateTaskType() function that validates the task_type parameter against supported values: intent, pii, security, all. Invalid values now return HTTP 400 with a clear error message:

curl -X POST localhost:8080/api/v1/classify/batch \
  -d '{"texts":["test"], "task_type":"jailbreak"}'

# Returns HTTP 400:
{
  "error": {
    "code": "INVALID_TASK_TYPE",
    "message": "invalid task_type 'jailbreak'. Supported values: [intent pii security all]",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

API Discovery Endpoint with Registry Pattern

Added GET /api/v1 endpoint that provides comprehensive API documentation, implemented using a centralized registry pattern for maintainability:

curl http://localhost:8080/api/v1

# Returns complete API overview with:
# - All available endpoints with descriptions
# - All supported task_types with descriptions
# - Links to documentation and resources

Registry-based implementation:

• endpointRegistry - centralized registry of all endpoint metadata
• taskTypeRegistry - centralized registry of all task types
• Documentation is generated dynamically from registries at runtime
• Automatically filters endpoints based on configuration (e.g., system prompts)

OpenAPI 3.0 Specification and Swagger UI

Added full OpenAPI 3.0 specification and interactive Swagger UI documentation:

GET /openapi.json - OpenAPI 3.0 Specification

• Complete OpenAPI 3.0 compliant specification
• Dynamically generated from endpoint registry
• Includes all endpoints with operations, request/response schemas
• Compatible with all OpenAPI tooling and generators
• Enables automatic client SDK generation

GET /docs - Interactive Swagger UI

• Browser-based interactive API documentation
• Try-it-out functionality for testing endpoints directly
• Real-time request/response visualization
• Schema exploration and examples
• Zero dependencies (CDN-loaded)

# Get OpenAPI spec
curl http://localhost:8080/openapi.json

# View interactive docs in browser
open http://localhost:8080/docs

Changes

• Added validateTaskType() helper function for input validation
• Integrated validation in handleBatchClassification() before processing requests
• Added GET /api/v1 API discovery endpoint with handleAPIOverview() handler
• Registry Pattern: Implemented centralized endpointRegistry and taskTypeRegistry for maintainable API documentation
• OpenAPI 3.0: Implemented complete OpenAPI 3.0 type structures and generateOpenAPISpec() function
• Added GET /openapi.json endpoint serving dynamically generated OpenAPI 3.0 specification
• Added GET /docs endpoint serving interactive Swagger UI
• Updated API overview to include links to OpenAPI spec and Swagger UI
• Added supporting types: APIOverviewResponse, EndpointInfo, TaskTypeInfo, EndpointMetadata, OpenAPISpec, OpenAPIOperation, etc.
• Added 12 comprehensive unit tests for validation, discovery, OpenAPI spec generation, and Swagger UI

Testing

All tests pass successfully:

• ✅ Invalid task_types (jailbreak, invalid_type) return HTTP 400 with helpful errors
• ✅ Valid task_types (intent, pii, security, all) are accepted
• ✅ Empty/omitted task_type defaults to intent (backward compatible)
• ✅ API overview endpoint returns complete documentation
• ✅ System prompt endpoints are properly filtered based on configuration
• ✅ OpenAPI 3.0 spec is correctly generated and structured
• ✅ OpenAPI spec includes/excludes endpoints based on configuration
• ✅ Swagger UI HTML is correctly rendered with proper references

Backward Compatibility

No breaking changes:

• Empty or omitted task_type still defaults to "intent"
• All valid task_type values continue to work as before
• Only previously invalid values (that were causing confusion) now return errors
• New documentation endpoints are purely additive

Impact

• Better UX: Users receive immediate feedback when using invalid parameters
• Faster debugging: Clear error messages show exactly what values are supported
• Improved discoverability: API capabilities are self-documented with interactive UI
• Industry standard: Full OpenAPI 3.0 specification and Swagger UI documentation
• Client SDK generation: OpenAPI spec enables automatic client library generation
• Maintainable: Registry pattern ensures documentation stays in sync with code
• Professional: Production-ready API documentation following best practices
• Interactive testing: Try endpoints directly in browser without writing code

Fixes the confusion around jailbreak detection - users now get a clear error pointing them to use task_type: "security" instead of guessing parameter names.

Fixes #321

Original prompt

---

This section details on the original issue you should resolve

<issue_title>API Discoverability and Silent Failure Issues</issue_title>
<issue_description>The Classification API lacks standard discovery mechanisms and silently accepts invalid parameters, leading to user confusion and incorrect usage.

🔍 API Discoverability Problems

❌ No Standard Discovery Endpoints

curl http://localhost:8080/docs          # 404
curl http://localhost:8080/openapi.json  # 404  
curl http://localhost:8080/api/v1/       # 404
curl http://localhost:8080/api           # 404

❌ No API Documentation Available

• No OpenAPI/Swagger specification
• No endpoint listing or overview
• No parameter documentation
• No examples or usage guides
• Users must guess parameters or read source code

🤫 Silent Failure Issues

Critical Problem: Invalid task_type Values Silently Default to Intent Classification

What Happens:

# All of these return the same result (intent classification):
curl -X POST localhost:8080/api/v1/classify/batch -d '{"texts":["test"], "task_type":"jailbreak"}'
curl -X POST localhost:8080/api/v1/classify/batch -d '{"texts":["test"], "task_type":"invalid_type"}'  
curl -X POST localhost:8080/api/v1/classify/batch -d '{"texts":["test"]}'

All return HTTP 200 with identical responses:

{
  "results": [{"category": "psychology", "confidence": 0.995}],
  "total_count": 1
}

Root Cause in Code

Lines 634-635 and 672-673 in server.go:

switch taskType {
case "pii":
    batchSize = len(unifiedResults.PIIResults)  
case "security":
    batchSize = len(unifiedResults.SecurityResults)
default:  // ← ANY invalid value falls here!
    batchSize = len(unifiedResults.IntentResults)
}

🎯 Real-World Impact

This caused confusion when testing jailbreak detection:

• Intuitive assumption: task_type: "jailbreak" should work for jailbreak detection
• Actual requirement: task_type: "security" is the correct parameter
• Result: Silent routing to wrong classifier, leading to incorrect test results
• Discovery: Only found through source code analysis and manual testing

🛠️ Proposed Solutions

1. Input Validation

func validateTaskType(taskType string) error {
    validTypes := []string{"intent", "pii", "security", "all"}
    if taskType != "" && !contains(validTypes, taskType) {
        return fmt.Errorf("invalid task_type '%s'. Supported values: %v", 
                         taskType, validTypes)
    }
    return nil
}

Expected Error Response (400 Bad Request):

{
  "error": {
    "code": "INVALID_TASK_TYPE",
    "message": "Invalid task_type 'jailbreak'. Supported values: ['intent', 'pii', 'security', 'all']",
    "supported_values": ["intent", "pii", "security", "all"]
  }
}

2. API Discovery Endpoints

GET /api/v1/                    # API overview with available endpoints
GET /api/v1/endpoints           # Detailed endpoint documentation  
GET /openapi.json              # OpenAPI 3.0 specification
GET /docs                      # Interactive Swagger UI documentation

3. Self-Documenting API Responses

{
  "results": [...],
  "metadata": {
    "task_type_used": "security",
    "available_task_types": ["intent", "pii", "security", "all"],
    "endpoint_docs": "/docs"
  }
}

4. Enhanced Error Messages

For missing/invalid parameters, provide helpful guidance:

{
  "error": {
    "message": "Invalid request",
    "details": "...",
    "documentation": "http://localhost:8080/docs",
    "examples": {
      "jailbreak_detection": "Use task_type: 'security' for jailbreak detection",
      "intent_classification": "Use task_type: 'intent' or omit for intent classification"
    }
  }
}

📊 Current API Endpoints (Discovered from Source)

For reference, here are the actual available endpoints:

POST /api/v1/classify/intent     # Single intent classification
POST /api/v1/classify/pii        # PII detection  
POST /api/v1/classify/security   # Security/jailbreak detection
POST /api/v1/classify/combined   # Combined classification
POST /api/v1/classify/batch      # Batch classification with task_type parameter
GET  /health                     # Health check
GET  /info/models               # Model information
GET  /v1/models                 # OpenAI-compatible model list

Valid task_type values for batch endpoint:

• "intent" - Intent/category classification (default)
• "pii" - PII detection
• "security" - Jailbreak/security detection
• "all" - All classification types

🎯 Benefits of Fixing This

1. Better UX: Users can discover API capabilities without reading source code
2. Faster onboarding: Clear documentation and examples
3. Fewer errors: Input validation catches mistakes early
4. Industry standard: OpenAPI specs and /docs endpoints are expected
5. Debugging: Clear error messages help users fix issues quickly

This issue affects A...

Fixes #321

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[netlify]

✅ Deploy Preview for vllm-semantic-router ready!

Name	Link
🔨 Latest commit	bb6f7d2
🔍 Latest deploy log	https://app.netlify.com/projects/vllm-semantic-router/deploys/68dfe99a18032e0008212317
😎 Deploy Preview	https://deploy-preview-326--vllm-semantic-router.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

👥 vLLM Semantic Team Notification

The following members have been identified for the changed files in this PR and have been automatically assigned:

📁 src

Owners: @rootfs, @Xunzhuo, @wangchen615
Files changed:

• src/semantic-router/pkg/api/server.go
• src/semantic-router/pkg/api/server_test.go

---

🎉 Thanks for your contributions!

This comment was automatically generated based on the OWNER files in the repository.

[rootfs]

@copilot can you use openapi generator instead of hardcode, so we can generate the spec for future api expansions.

[Copilot]

@copilot can you use openapi generator instead of hardcode, so we can generate the spec for future api expansions.

Refactored to use a centralized registry pattern in commit 34001e2.

Instead of hardcoding endpoints in the handler, I created:

• endpointRegistry - single source of truth for all endpoint metadata
• taskTypeRegistry - single source of truth for task types
• Dynamic generation of API documentation from these registries

This approach:

• Eliminates hardcoding in handler functions
• Makes adding new endpoints easy (just add to registry)
• Provides foundation for future OpenAPI spec generation
• Enables dynamic filtering (e.g., system prompt endpoints based on config)

The registry pattern allows future enhancements like generating full OpenAPI 3.0 specs at /openapi.json and serving Swagger UI at /docs by simply iterating over the registries to build the specification.

[rootfs]

@copilot add full OpenAPI 3.0 specs at /openapi.json and serving Swagger UI at /docs

[Copilot]

@copilot add full OpenAPI 3.0 specs at /openapi.json and serving Swagger UI at /docs

Implemented in commit bb6f7d2.

Added two new endpoints:

GET /openapi.json - Full OpenAPI 3.0 specification

• Dynamically generated from endpoint registry
• Includes all endpoints, operations, request/response schemas
• Automatically filters based on server configuration
• Standard-compliant spec for tooling integration

GET /docs - Interactive Swagger UI

• Browser-based API documentation interface
• Try-it-out functionality for all endpoints
• Schema visualization and examples
• Zero dependencies (CDN-loaded)

Both endpoints are generated from the centralized registry, ensuring documentation always matches the actual API. The spec can be used to generate client SDKs with tools like openapi-generator or swagger-codegen.

Access the interactive docs at http://localhost:8080/docs and the spec at http://localhost:8080/openapi.json.