Clean up API documentation

[domdomegg]

• Move API examples from docs into swagger.yaml
• Align openapi.yaml docs with implementation

Original: #229

[domdomegg]

@claude review please

[claude]

Claude finished @domdomegg's task —— View job

---

PR Review: Clean up API documentation ✅

Summary: This PR consolidates API documentation by removing duplicate content and centralizing documentation around the Swagger UI endpoint. The cleanup removes redundant examples and obsolete specification files while maintaining comprehensive documentation through the live Swagger interface.

Review Status:

• Analyze all changed files and understand the scope
• Review deleted files to ensure important content wasn't lost
• Check OpenAPI specification changes for accuracy
• Verify documentation consistency and completeness
• Provide comprehensive review feedback

✅ Approval - Excellent Documentation Cleanup

This is a well-executed documentation consolidation that improves maintainability and user experience. Here's my detailed analysis:

What This PR Does Well:

1. Consolidates Documentation Sources

   • Removes 200+ lines of redundant API examples from README.md
   • Deletes standalone examples.md (293 lines) whose content was migrated to swagger.yaml
   • Removes official-registry-openapi.yaml (42 lines) - a derivative spec that added constraints

2. Improves Documentation Architecture

   • Centralizes API documentation around /v0/swagger/index.html endpoint
   • Updates all references to point to the correct swagger.yaml file
   • Maintains clear separation between generic API spec (openapi.yaml) and implementation-specific spec (swagger.yaml)

3. No Information Loss

   • The examples from examples.md were previously moved into swagger.yaml (commit f670b55)
   • The constraints from official-registry-openapi.yaml are already in swagger.yaml
   • README still points users to the interactive Swagger UI for complete API documentation

Documentation Structure (Post-cleanup):

• docs/server-registry-api/openapi.yaml - Generic MCP Server Registry API specification
• internal/docs/swagger.yaml - Official MCP Registry implementation with examples and constraints
• /v0/swagger/index.html - Interactive documentation endpoint for users

Reference Updates Are Correct:

• ✅ docs/faq.md:19 now correctly references swagger.yaml instead of the deleted official-registry-openapi.yaml
• ✅ docs/server-registry-api/README.md:13 now correctly references swagger.yaml

Minor Observations:

• The git diff shows many other changes (.env.example, workflows, Go version updates) that aren't related to API documentation cleanup - these appear to be incidental changes from the branch rebase/recreation mentioned in the PR description
• The core documentation changes are clean and purposeful

User Impact:

• Positive: Users get a single, comprehensive, interactive API documentation experience
• Positive: Developers have less duplicate content to maintain
• Positive: Clear separation between generic API spec and implementation-specific documentation

This cleanup significantly improves the documentation maintainability while providing users with a better experience through the interactive Swagger UI. The consolidation eliminates redundancy without losing any important information.

Recommendation: ✅ Approve and merge

---

[crondinini-ant]

✅

[domdomegg]

// approving based on @.camirondi's review - she's joining the MCP team but just hasn't got the GitHub perms quite set up yet :)

[tadasant]

@domdomegg do you have some replacement for api_examples.md we can reference instead? We've been referencing this file very heavily while iterating on the shapes - it's a lot easier to grok and talk about examples than it is to read the schemas.

[domdomegg]

A difficulty was they get out of date very quickly - https://registry.modelcontextprotocol.io/docs does have examples that people can poke around in.

And 90% of the complexity is in server.json, where I've kept the examples.

[tadasant]

And 90% of the complexity is in server.json, where I've kept the examples.

Got it - wasn't sure if you were planning to do the same for those, but if we're keeping those then I'm ok dropping these for maintainability.

I'll also close #239 as I think this change supersedes that

[domdomegg]

Sounds good!