api: Use Huma to generate swagger docs and parse JSON automatically (#262)

## Motivation and Context

Currently there's a lot of unsafe manual JSON unmarshalling/marshalling,
and we have to manually keep the openapi schema in sync.

This PR migrates the API to
[Huma](https://github.com/danielgtaylor/huma), which appears like a
popular, well-maintained way to build APIs in Golang. I'm not a Golang
expert, but seemed highly recommended by Reddit + Claude and has a
decent star count. It provides automatic openapi spec generation and
docs hosting, JSON parsing, as well as the ability to add auth
middlewares etc.

## How Has This Been Tested?

Running locally, and poking at the endpoints

## Breaking Changes

Docs are served at `/docs` rather than `/v0/swagger/index.html` now

## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update

## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [x] I have added or updated documentation as needed

## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
This commit is contained in:
adam jones 2025-08-13 16:57:55 +01:00 • committed by GitHub
commit 6b84493ca9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -1,24 +1,24 @@
package v0_test
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"testing"
"github.com/danielgtaylor/huma/v2"
"github.com/danielgtaylor/huma/v2/adapters/humago"
v0 "github.com/modelcontextprotocol/registry/internal/api/handlers/v0"
"github.com/modelcontextprotocol/registry/internal/config"
"github.com/stretchr/testify/assert"
)
func TestHealthHandler(t *testing.T) {
func TestHealthEndpoint(t *testing.T) {
// Test cases
testCases := []struct {
name string
config *config.Config
expectedStatus int
expectedBody v0.HealthResponse
expectedBody v0.HealthBody
}{
{
name: "returns health status with github client id",
@ -26,18 +26,18 @@ func TestHealthHandler(t *testing.T) {
GithubClientID: "test-github-client-id",
},
expectedStatus: http.StatusOK,
expectedBody: v0.HealthResponse{
expectedBody: v0.HealthBody{
Status: "ok",
GitHubClientID: "test-github-client-id",
},
},
{
name: "works with empty github client id",
name: "returns health status without github client id",
config: &config.Config{
GithubClientID: "",
},
expectedStatus: http.StatusOK,
expectedBody: v0.HealthResponse{
expectedBody: v0.HealthBody{
Status: "ok",
GitHubClientID: "",
},
@ -46,77 +46,33 @@ func TestHealthHandler(t *testing.T) {
for _, tc := range testCases {
t.Run(tc.name, func(t *testing.T) {
// Create handler with the test config
handler := v0.HealthHandler(tc.config)
// Create a new test API
mux := http.NewServeMux()
api := humago.New(mux, huma.DefaultConfig("Test API", "1.0.0"))
// Register the health endpoint
v0.RegisterHealthEndpoint(api, tc.config)
// Create request
req, err := http.NewRequestWithContext(context.Background(), http.MethodGet, "/health", nil)
if err != nil {
t.Fatal(err)
}
// Create a test request
req := httptest.NewRequest(http.MethodGet, "/v0/health", nil)
w := httptest.NewRecorder()
// Create response recorder
rr := httptest.NewRecorder()
// Serve the request
mux.ServeHTTP(w, req)
// Call the handler
handler.ServeHTTP(rr, req)
// Check status code
assert.Equal(t, tc.expectedStatus, rr.Code)
// Check content type
assert.Equal(t, "application/json", rr.Header().Get("Content-Type"))
// Parse response body
var resp v0.HealthResponse
err = json.NewDecoder(rr.Body).Decode(&resp)
assert.NoError(t, err)
// Check the status code
assert.Equal(t, tc.expectedStatus, w.Code)
// Check the response body
assert.Equal(t, tc.expectedBody, resp)
// Since Huma adds a $schema field, we'll check individual fields
body := w.Body.String()
assert.Contains(t, body, `"status":"ok"`)
if tc.config.GithubClientID != "" {
assert.Contains(t, body, `"github_client_id":"test-github-client-id"`)
} else {
assert.NotContains(t, body, `"github_client_id"`)
}
})
}
}
// TestHealthHandlerIntegration tests the handler with actual HTTP requests
func TestHealthHandlerIntegration(t *testing.T) {
// Create test server
cfg := &config.Config{
GithubClientID: "integration-test-client-id",
}
server := httptest.NewServer(v0.HealthHandler(cfg))
defer server.Close()
// Send request to the test server
ctx := context.Background()
req, err := http.NewRequestWithContext(ctx, http.MethodGet, server.URL, nil)
if err != nil {
t.Fatalf("Failed to create request: %v", err)
}
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
t.Fatalf("Failed to send request: %v", err)
}
defer resp.Body.Close()
// Check status code
assert.Equal(t, http.StatusOK, resp.StatusCode)
// Check content type
assert.Equal(t, "application/json", resp.Header.Get("Content-Type"))
// Parse response body
var healthResp v0.HealthResponse
err = json.NewDecoder(resp.Body).Decode(&healthResp)
assert.NoError(t, err)
// Check the response body
expectedResp := v0.HealthResponse{
Status: "ok",
GitHubClientID: "integration-test-client-id",
}
assert.Equal(t, expectedResp, healthResp)
}
}