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

@ -57,17 +57,14 @@ const (
FormatFilePath Format = "file_path"
)
// UserInput represents a user input as defined in the spec
type Input struct {
Description string `json:"description,omitempty" bson:"description,omitempty"`
IsRequired bool `json:"is_required,omitempty" bson:"is_required,omitempty"`
Format Format `json:"format,omitempty" bson:"format,omitempty"`
Value string `json:"value,omitempty" bson:"value,omitempty"`
IsSecret bool `json:"is_secret,omitempty" bson:"is_secret,omitempty"`
Default string `json:"default,omitempty" bson:"default,omitempty"`
Choices []string `json:"choices,omitempty" bson:"choices,omitempty"`
Template string `json:"template,omitempty" bson:"template,omitempty"`
Properties map[string]Input `json:"properties,omitempty" bson:"properties,omitempty"`
Description string `json:"description,omitempty" bson:"description,omitempty"`
IsRequired bool `json:"is_required,omitempty" bson:"is_required,omitempty"`
Format Format `json:"format,omitempty" bson:"format,omitempty"`
Value string `json:"value,omitempty" bson:"value,omitempty"`
IsSecret bool `json:"is_secret,omitempty" bson:"is_secret,omitempty"`
Default string `json:"default,omitempty" bson:"default,omitempty"`
Choices []string `json:"choices,omitempty" bson:"choices,omitempty"`
}
type InputWithVariables struct {
@ -107,25 +104,25 @@ type Package struct {
// Remote represents a remote connection endpoint
type Remote struct {
TransportType string `json:"transport_type" bson:"transport_type"`
URL string `json:"url" bson:"url"`
Headers []Input `json:"headers,omitempty" bson:"headers,omitempty"`
TransportType string `json:"transport_type" bson:"transport_type"`
URL string `json:"url" bson:"url"`
Headers []KeyValueInput `json:"headers,omitempty" bson:"headers,omitempty"`
}
// VersionDetail represents the version details of a server
type VersionDetail struct {
Version string `json:"version" bson:"version"`
ReleaseDate string `json:"release_date" bson:"release_date"`
IsLatest bool `json:"is_latest" bson:"is_latest"`
ReleaseDate string `json:"release_date,omitempty" bson:"release_date"`
IsLatest bool `json:"is_latest,omitempty" bson:"is_latest"`
}
// Server represents a basic server information as defined in the spec
type Server struct {
ID string `json:"id" bson:"id"`
ID string `json:"id,omitempty" bson:"id"`
Name string `json:"name" bson:"name"`
Description string `json:"description" bson:"description"`
Status ServerStatus `json:"status,omitempty" bson:"status,omitempty"`
Repository Repository `json:"repository" bson:"repository"`
Repository Repository `json:"repository,omitempty" bson:"repository"`
VersionDetail VersionDetail `json:"version_detail" bson:"version_detail"`
}