From cce5e5df4678f0b0076d2297e953b59203ed0562 Mon Sep 17 00:00:00 2001
From: Aleksandr Beshkenadze <beshkenadze@gmail.com>
Date: Tue, 14 Oct 2025 14:30:36 +0300
Subject: [PATCH] feat: add OpenAPI tags for improved SDK generation and API
 organization (#655)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary
Adds OpenAPI tags to improve SDK generation and API documentation
organization, as discussed in #644.

## Changes
- **Go Code**: Define tag metadata (name + description) in
`internal/api/router/router.go` using Huma's `api.OpenAPI().Tags`
- **Reference Spec**: Update `docs/reference/api/openapi.yaml` to match
the generated spec
- **Tags Added**: servers, publish, auth, admin, health, ping

## Benefits
- ✅ Improved SDK generation with proper service grouping (e.g.,
`serversService`, `publishService`)
- ✅ Better API documentation organization in Scalar UI, Swagger UI, and
other tools
- ✅ Code-first approach ensures reference spec stays in sync via
compliance tests

## Testing
- ✅ Compliance test passes: `go test -v ./internal/api -run
TestOpenAPIEndpointCompliance`
- ✅ All 4 reference endpoints verified as implemented
- ✅ TypeScript SDK regenerated successfully with proper tag-based
grouping

## Related
Closes #644
---
 docs/reference/api/openapi.yaml | 14 ++++++++++++--
 internal/api/router/router.go   | 12 ++++++++++++
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/docs/reference/api/openapi.yaml b/docs/reference/api/openapi.yaml
index 50b46c6..f20e9b3 100644
--- a/docs/reference/api/openapi.yaml
+++ b/docs/reference/api/openapi.yaml
@@ -11,9 +11,16 @@ info:
     name: MIT
     identifier: MIT
 
+tags:
+  - name: servers
+    description: Operations for discovering and retrieving MCP servers
+  - name: publish
+    description: Operations for publishing MCP servers to the registry
+
 paths:
   /v0/servers:
     get:
+      tags: [servers]
       summary: List MCP servers
       description: Returns a list of all registered MCP servers
       parameters:
@@ -41,6 +48,7 @@ paths:
                 $ref: '#/components/schemas/ServerList'
   /v0/servers/{serverName}/versions:
     get:
+      tags: [servers]
       summary: List all versions of an MCP server
       description: Returns all available versions for a specific MCP server, ordered by publication date (newest first)
       parameters:
@@ -70,6 +78,7 @@ paths:
                     example: "Server not found"
   /v0/servers/{serverName}/versions/{version}:
     get:
+      tags: [servers]
       summary: Get specific MCP server version
       description: Returns detailed information about a specific version of an MCP server. Use the special version `latest` to get the latest version.
       parameters:
@@ -106,12 +115,13 @@ paths:
                     example: "Server not found"
   /v0/publish:
     post:
+      tags: [publish]
       summary: Publish MCP server (Optional)
       description: |
         Publish a new MCP server to the registry or update an existing one.
-        
+
         **Note**: This endpoint is optional for registry implementations. Read-only registries may not provide this functionality.
-        
+
         Authentication mechanism is registry-specific and may vary between implementations.
       security:
         - bearerAuth: []
diff --git a/internal/api/router/router.go b/internal/api/router/router.go
index 0907132..cb29b10 100644
--- a/internal/api/router/router.go
+++ b/internal/api/router/router.go
@@ -139,6 +139,18 @@ func NewHumaAPI(cfg *config.Config, registry service.RegistryService, mux *http.
 	// Create a new API using humago adapter for standard library
 	api := humago.New(mux, humaConfig)
 
+	// Add OpenAPI tag metadata with descriptions
+	api.OpenAPI().Tags = []*huma.Tag{
+		{
+			Name:        "servers",
+			Description: "Operations for discovering and retrieving MCP servers",
+		},
+		{
+			Name:        "publish",
+			Description: "Operations for publishing MCP servers to the registry",
+		},
+	}
+
 	// Add metrics middleware with options
 	api.UseMiddleware(MetricTelemetryMiddleware(metrics,
 		WithSkipPaths("/health", "/metrics", "/ping", "/docs"),