feat: add OpenAPI tags for improved SDK generation and API organization (#655)

## 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

Author: beshkenadze

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: []

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"),