fix: Remove duplicate endpoint registrations breaking Swagger/OpenAPI generation

Resolves Swagger conflict causing OpenAPI export to fail with HTTP 500 error.

Root Cause:
- OpenHarbor.CQRS v8.1.0-rc1 auto-registers and auto-documents ALL ICommandHandler and IQueryHandler implementations
- ManualEndpointRegistration.cs contained duplicate registrations for:
  * Commands: CreateConversation, StartAgentExecution
  * Queries: GetAgentExecution, GetConversation
- Duplicate routes violated OpenAPI 3.0 requirement for unique method/path combinations

Changes:
- Removed duplicate command registrations (lines 30-92)
- Removed duplicate query registrations (lines 44-124)
- Added explanatory comments about framework auto-registration
- File reduced from ~450 lines to ~320 lines

Impact:
-  Swagger endpoint now returns HTTP 200 (was HTTP 500)
-  OpenAPI export successful: docs/openapi.json (34KB, was 524B error)
-  All 16 endpoints properly documented
-  Frontend team can now generate TypeScript client
-  export-openapi.sh script working correctly

Verified:
- Valid OpenAPI 3.0.1 JSON structure
- 6 commands + 4 queries + 6 simple endpoints = 16 total
- No more route conflicts

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2025-10-26 20:19:58 -04:00
parent c666f6b8d0
commit f5a5c5697c
2 changed files with 757 additions and 229 deletions
+734
View File
@@ -6,6 +6,139 @@
"version": "v1"
},
"paths": {
"/api/agents": {
"get": {
"tags": [
"Agents"
],
"summary": "Get all agents",
"description": "Returns a list of all active agents with metadata. Limit: 100 most recent.",
"operationId": "GetAllAgents",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { }
}
}
}
}
}
},
"/api/agents/{id}/conversations": {
"get": {
"tags": [
"Agents"
],
"summary": "Get conversations for an agent",
"description": "Returns all conversations associated with a specific agent.",
"operationId": "GetAgentConversations",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { }
}
}
}
}
}
},
"/api/agents/{id}/executions": {
"get": {
"tags": [
"Agents"
],
"summary": "Get execution history for an agent",
"description": "Returns the 100 most recent executions for a specific agent.",
"operationId": "GetAgentExecutions",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { }
}
}
}
}
}
},
"/api/command/completeAgentExecution": {
"post": {
"tags": [
"completeAgentExecution"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteAgentExecutionCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CompleteAgentExecutionCommand"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CompleteAgentExecutionCommand"
}
}
}
},
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/api/conversations": {
"get": {
"tags": [
"Conversations"
],
"summary": "Get all conversations",
"description": "Returns the 100 most recent conversations.",
"operationId": "GetAllConversations",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { }
}
}
}
}
}
},
"/api/command/createAgent": {
"post": {
"tags": [
@@ -37,6 +170,45 @@
}
}
},
"/api/command/createConversation": {
"post": {
"tags": [
"createConversation"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateConversationCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/CreateConversationCommand"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/CreateConversationCommand"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "string",
"format": "uuid"
}
}
}
}
}
}
},
"/api/command/deleteAgent": {
"post": {
"tags": [
@@ -68,6 +240,59 @@
}
}
},
"/api/executions": {
"get": {
"tags": [
"Executions"
],
"summary": "Get all executions",
"description": "Returns the 100 most recent executions across all agents.",
"operationId": "GetAllExecutions",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { }
}
}
}
}
}
},
"/api/executions/status/{status}": {
"get": {
"tags": [
"Executions"
],
"summary": "Get executions by status",
"description": "Returns executions filtered by status (Pending, Running, Completed, Failed, Cancelled).",
"operationId": "GetExecutionsByStatus",
"parameters": [
{
"name": "status",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { }
}
}
},
"400": {
"description": "Bad Request"
}
}
}
},
"/api/query/getAgent": {
"post": {
"tags": [
@@ -134,6 +359,138 @@
}
}
},
"/api/query/getAgentExecution": {
"post": {
"tags": [
"getAgentExecution"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetAgentExecutionQuery"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GetAgentExecutionQuery"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/GetAgentExecutionQuery"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentExecutionDetails"
}
}
}
}
}
},
"get": {
"tags": [
"getAgentExecution"
],
"parameters": [
{
"name": "Id",
"in": "query",
"description": "Execution ID",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentExecutionDetails"
}
}
}
}
}
}
},
"/api/query/getConversation": {
"post": {
"tags": [
"getConversation"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetConversationQuery"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/GetConversationQuery"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/GetConversationQuery"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationDetails"
}
}
}
}
}
},
"get": {
"tags": [
"getConversation"
],
"parameters": [
{
"name": "Id",
"in": "query",
"description": "Conversation ID",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationDetails"
}
}
}
}
}
}
},
"/api/query/health": {
"post": {
"tags": [
@@ -198,6 +555,45 @@
}
}
},
"/api/command/startAgentExecution": {
"post": {
"tags": [
"startAgentExecution"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StartAgentExecutionCommand"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/StartAgentExecutionCommand"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/StartAgentExecutionCommand"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "string",
"format": "uuid"
}
}
}
}
}
}
},
"/api/command/updateAgent": {
"post": {
"tags": [
@@ -232,6 +628,108 @@
},
"components": {
"schemas": {
"AgentExecutionDetails": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique execution identifier",
"format": "uuid"
},
"agentId": {
"type": "string",
"description": "Agent identifier",
"format": "uuid"
},
"agentName": {
"type": "string",
"description": "Agent name",
"nullable": true
},
"conversationId": {
"type": "string",
"description": "Conversation identifier if part of a conversation",
"format": "uuid",
"nullable": true
},
"userPrompt": {
"type": "string",
"description": "Full user prompt",
"nullable": true
},
"input": {
"type": "string",
"description": "Additional input context or parameters",
"nullable": true
},
"output": {
"type": "string",
"description": "Agent's complete output/response",
"nullable": true
},
"status": {
"$ref": "#/components/schemas/ExecutionStatus"
},
"startedAt": {
"type": "string",
"description": "Execution start timestamp",
"format": "date-time"
},
"completedAt": {
"type": "string",
"description": "Execution completion timestamp",
"format": "date-time",
"nullable": true
},
"executionTimeMs": {
"type": "integer",
"description": "Execution time in milliseconds",
"format": "int64",
"nullable": true
},
"inputTokens": {
"type": "integer",
"description": "Input tokens consumed",
"format": "int32",
"nullable": true
},
"outputTokens": {
"type": "integer",
"description": "Output tokens generated",
"format": "int32",
"nullable": true
},
"totalTokens": {
"type": "integer",
"description": "Total tokens used",
"format": "int32",
"nullable": true
},
"estimatedCost": {
"type": "number",
"description": "Estimated cost in USD",
"format": "double",
"nullable": true
},
"toolCalls": {
"type": "string",
"description": "Tool calls made during execution (JSON array)",
"nullable": true
},
"toolCallResults": {
"type": "string",
"description": "Tool execution results (JSON array)",
"nullable": true
},
"errorMessage": {
"type": "string",
"description": "Error message if execution failed",
"nullable": true
}
},
"additionalProperties": false,
"description": "Detailed agent execution information"
},
"AgentStatus": {
"enum": [
"Active",
@@ -252,6 +750,153 @@
"type": "string",
"description": "Specifies the type/purpose of the agent."
},
"CompleteAgentExecutionCommand": {
"type": "object",
"properties": {
"executionId": {
"type": "string",
"description": "Execution ID to complete",
"format": "uuid"
},
"output": {
"type": "string",
"description": "Agent's output/response",
"nullable": true
},
"status": {
"$ref": "#/components/schemas/ExecutionStatus"
},
"inputTokens": {
"type": "integer",
"description": "Input tokens consumed",
"format": "int32",
"nullable": true
},
"outputTokens": {
"type": "integer",
"description": "Output tokens generated",
"format": "int32",
"nullable": true
},
"estimatedCost": {
"type": "number",
"description": "Estimated cost in USD",
"format": "double",
"nullable": true
},
"toolCalls": {
"type": "string",
"description": "Tool calls made (JSON array)",
"nullable": true
},
"toolCallResults": {
"type": "string",
"description": "Tool call results (JSON array)",
"nullable": true
},
"errorMessage": {
"type": "string",
"description": "Error message if failed",
"nullable": true
}
},
"additionalProperties": false,
"description": "Completes an agent execution with results and metrics"
},
"ConversationDetails": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique conversation identifier",
"format": "uuid"
},
"title": {
"type": "string",
"description": "Conversation title",
"nullable": true
},
"summary": {
"type": "string",
"description": "Conversation summary",
"nullable": true
},
"isActive": {
"type": "boolean",
"description": "Whether conversation is active"
},
"startedAt": {
"type": "string",
"description": "Conversation start timestamp",
"format": "date-time"
},
"lastMessageAt": {
"type": "string",
"description": "Last message timestamp",
"format": "date-time"
},
"messageCount": {
"type": "integer",
"description": "Total message count",
"format": "int32"
},
"messages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConversationMessageItem"
},
"description": "All messages in conversation",
"nullable": true
}
},
"additionalProperties": false,
"description": "Detailed conversation information with messages"
},
"ConversationMessageItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Message identifier",
"format": "uuid"
},
"conversationId": {
"type": "string",
"description": "Conversation identifier",
"format": "uuid"
},
"executionId": {
"type": "string",
"description": "Execution identifier if from agent execution",
"format": "uuid",
"nullable": true
},
"role": {
"$ref": "#/components/schemas/MessageRole"
},
"content": {
"type": "string",
"description": "Message content",
"nullable": true
},
"messageIndex": {
"type": "integer",
"description": "Message index/order in conversation",
"format": "int32"
},
"isInActiveWindow": {
"type": "boolean",
"description": "Whether message is in active context window"
},
"createdAt": {
"type": "string",
"description": "Message creation timestamp",
"format": "date-time"
}
},
"additionalProperties": false,
"description": "Individual message within a conversation"
},
"CreateAgentCommand": {
"type": "object",
"properties": {
@@ -319,6 +964,23 @@
"additionalProperties": false,
"description": "Command to create a new AI agent with configuration"
},
"CreateConversationCommand": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Conversation title",
"nullable": true
},
"summary": {
"type": "string",
"description": "Optional summary or description",
"nullable": true
}
},
"additionalProperties": false,
"description": "Creates a new conversation for grouping related messages"
},
"DeleteAgentCommand": {
"type": "object",
"properties": {
@@ -331,6 +993,28 @@
"additionalProperties": false,
"description": "Command to soft-delete an agent"
},
"ExecutionStatus": {
"enum": [
"Running",
"Completed",
"Failed",
"Cancelled"
],
"type": "string",
"description": "Represents the status of an agent execution."
},
"GetAgentExecutionQuery": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Execution ID",
"format": "uuid"
}
},
"additionalProperties": false,
"description": "Get detailed agent execution by ID"
},
"GetAgentQuery": {
"type": "object",
"properties": {
@@ -410,11 +1094,33 @@
"additionalProperties": false,
"description": "Response containing agent details"
},
"GetConversationQuery": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Conversation ID",
"format": "uuid"
}
},
"additionalProperties": false,
"description": "Get conversation with all messages by ID"
},
"HealthQuery": {
"type": "object",
"additionalProperties": false,
"description": "Health check query to verify API availability"
},
"MessageRole": {
"enum": [
"User",
"Assistant",
"System",
"Tool"
],
"type": "string",
"description": "Represents the role of a message in a conversation."
},
"ModelProviderType": {
"enum": [
"CloudApi",
@@ -424,6 +1130,34 @@
"type": "string",
"description": "Specifies the type of model provider (cloud API or local endpoint)."
},
"StartAgentExecutionCommand": {
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "Agent ID to execute",
"format": "uuid"
},
"userPrompt": {
"type": "string",
"description": "User's input prompt",
"nullable": true
},
"conversationId": {
"type": "string",
"description": "Optional conversation ID to link execution to",
"format": "uuid",
"nullable": true
},
"input": {
"type": "string",
"description": "Optional additional input context (JSON)",
"nullable": true
}
},
"additionalProperties": false,
"description": "Starts a new agent execution"
},
"UpdateAgentCommand": {
"type": "object",
"properties": {