Add OpenAPI tags for each endpoint in openapi.yaml to improve SDK generation and grouping

[beshkenadze]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

Idea

The current openapi.yaml defines endpoints (/v0/servers, /v0/publish, etc.) without any tags field.
This makes auto-generated SDKs (e.g., using Kubb, OpenAPI Generator, or Swagger Codegen) group all methods under undefinedService, since no tags are provided.

Adding simple tags per endpoint will:

• Make the generated SDK structure cleaner (serversService, publishingService, etc.)
• Improve API documentation grouping (in Swagger UI or Redoc)
• Align the registry spec with OpenAPI best practices

---

Example

paths:
  /v0/servers:
    get:
      tags: [servers]
      summary: List MCP servers

  /v0/servers/{serverName}/versions:
    get:
      tags: [servers]
      summary: List all versions of an MCP server

  /v0/servers/{serverName}/versions/{version}:
    get:
      tags: [servers]
      summary: Get specific MCP server version

  /v0/publish:
    post:
      tags: [publishing]
      summary: Publish MCP server

---

Benefits

• Cleaner SDKs: serversService, publishingService
• Better structure in OpenAPI viewers (Swagger / Redoc)
• Easier maintenance and navigation
• No breaking changes — purely additive improvement

---

Who Benefits

• SDK and tooling authors generating code from the spec
• Developers consuming the registry API
• Anyone exploring the API through documentation tools

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[rdimitrov]

hey, @beshkenadze, I think that sounds reasonable 👍 Would you be interested in contributing this?

[beshkenadze]

I'm not very familiar with Go, but I don't see who generates the openapi.yaml file. Isn't it an auto-generated file?

[rdimitrov]

The OpenAPI schema served by the registry server already defines the tags (publishing is publish) and that part’s auto-generated by Huma 👍 The reference OpenAPI file, however, is maintained manually, so we can align it by hand.

I don't see any downsides of adding the tags there for consistency so feel free to open a PR if you’re up for it! Otherwise, we can do it too, I just didn’t want to take credit for your idea 🙌

[beshkenadze]

This has been implemented in PR #665 which adds an OpenAPI export CLI tool that automatically generates OpenAPI specifications from the Huma API routes.

The tool supports:

• Multiple output formats (OpenAPI 3.1 and 3.0, JSON and YAML)
• Makefile integration with `make generate-openapi`
• Automated spec generation for SDK generation and documentation

See the PR for full details: #665

[beshkenadze]

Hi @rdimitrov — thanks for your feedback!
Could you please also take a look at #665? It implements an OpenAPI export CLI tool that helps auto-generate the spec (including tags) from the Huma API routes.

Let me know if you’d like me to adjust it or provide more context.