docs: Clean up API documentation (#236)

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

Author: domdomegg

README.md

@@ -200,206 +200,7 @@ Publishing requires GitHub OAuth validation:
 GET /v0/swagger/index.html
 ```
 
-The API is documented using Swagger/OpenAPI. This page provides a complete reference of all endpoints with request/response schemas and allows you to test the API directly from your browser.
-
-### Health Check
-
-```
-GET /v0/health
-```
-
-Returns the health status of the service:
-```json
-{
-  "status": "ok"
-}
-```
-
-### Registry Endpoints
-
-#### List Registry Server Entries
-
-```
-GET /v0/servers
-```
-
-Lists MCP registry server entries with pagination support.
-
-Query parameters:
-- `limit`: Maximum number of entries to return (default: 30, max: 100)
-- `cursor`: Pagination cursor for retrieving next set of results
-
-Response example:
-```json
-{
-  "servers": [
-    {
-      "id": "123e4567-e89b-12d3-a456-426614174000",
-      "name": "Example MCP Server",
-      "url": "https://example.com/mcp",
-      "description": "An example MCP server",
-      "created_at": "2025-05-17T17:34:22.912Z",
-      "updated_at": "2025-05-17T17:34:22.912Z"
-    }
-  ],
-  "metadata": {
-    "next_cursor": "123e4567-e89b-12d3-a456-426614174000",
-    "count": 30
-  }
-}
-```
-
-#### Get Server Details
-
-```
-GET /v0/servers/{id}
-```
-
-Retrieves detailed information about a specific MCP server entry.
-
-Path parameters:
-- `id`: Unique identifier of the server entry
-
-Response example:
-```json
-{
-  "id": "01129bff-3d65-4e3d-8e82-6f2f269f818c",
-  "name": "io.github.gongrzhe/redis-mcp-server",
-  "description": "A Redis MCP server (pushed to https://github.com/modelcontextprotocol/servers/tree/main/src/redis) implementation for interacting with Redis databases. This server enables LLMs to interact with Redis key-value stores through a set of standardized tools.",
-  "repository": {
-    "url": "https://github.com/GongRzhe/REDIS-MCP-Server",
-    "source": "github",
-    "id": "907849235"
-  },
-  "version_detail": {
-    "version": "0.0.1-seed",
-    "release_date": "2025-05-16T19:13:21Z",
-    "is_latest": true
-  },
-  "packages": [
-    {
-      "registry_name": "docker",
-      "name": "@gongrzhe/server-redis-mcp",
-      "version": "1.0.0",
-      "package_arguments": [
-        {
-          "description": "Docker image to run",
-          "is_required": true,
-          "format": "string",
-          "value": "mcp/redis",
-          "default": "mcp/redis",
-          "type": "positional",
-          "value_hint": "mcp/redis"
-        },
-        {
-          "description": "Redis server connection string",
-          "is_required": true,
-          "format": "string",
-          "value": "redis://host.docker.internal:6379",
-          "default": "redis://host.docker.internal:6379",
-          "type": "positional",
-          "value_hint": "host.docker.internal:6379"
-        }
-      ]
-    }
-  ]
-}
-```
-
-#### Publish a Server Entry
-
-```
-POST /v0/publish
-```
-
-Publishes a new MCP server entry to the registry. Authentication is required via Bearer token in the Authorization header.
-
-Headers:
-- `Authorization`: Bearer token for authentication (e.g., `Bearer your_token_here`)
-- `Content-Type`: application/json
-
-Request body example:
-```json
-{
-    "description": "<your description here>",
-    "name": "io.github.<owner>/<server-name>",
-    "packages": [
-        {
-            "registry_name": "npm",
-            "name": "@<owner>/<server-name>",
-            "version": "0.2.23",
-            "package_arguments": [
-                {
-                    "description": "Specify services and permissions.",
-                    "is_required": true,
-                    "format": "string",
-                    "value": "-s",
-                    "default": "-s",
-                    "type": "positional",
-                    "value_hint": "-s"
-                }
-            ],
-            "environment_variables": [
-                {
-                    "description": "API Key to access the server",
-                    "name": "API_KEY"
-                }
-            ]
-        },{
-            "registry_name": "docker",
-            "name": "@<owner>/<server-name>-cli",
-            "version": "0.123.223",
-            "runtime_hint": "docker",
-            "runtime_arguments": [
-                {
-                    "description": "Specify services and permissions.",
-                    "is_required": true,
-                    "format": "string",
-                    "value": "--mount",
-                    "default": "--mount",
-                    "type": "positional",
-                    "value_hint": "--mount"
-                }
-            ],
-            "environment_variables": [
-                {
-                    "description": "API Key to access the server",
-                    "name": "API_KEY"
-                }
-            ]
-        }
-    ],
-    "repository": {
-        "url": "https://github.com/<owner>/<server-name>",
-        "source": "github"
-    },
-    "version_detail": {
-        "version": "0.0.1-<publisher_version>"
-    }
-}
-```
-
-Response example:
-```json
-{
-  "message": "Server publication successful",
-  "id": "1234567890abcdef12345678"
-}
-```
-
-### Ping Endpoint
-
-```
-GET /v0/ping
-```
-
-Simple ping endpoint that returns environment configuration information:
-```json
-{
-  "environment": "dev",
-  "version": "registry-<sha>"
-}
-```
+The API is documented using Swagger/OpenAPI. This page provides a complete reference of all endpoints with request/response schemas and examples, and allows you to test the API directly from your browser.
 
 ## Configuration
 

docs/faq.md

@@ -18,7 +18,7 @@ The MCP Registry is the official centralized metadata repository for publicly-ac
 There are four underlying concepts:
 - "MCP Server Registry API" (or "MCP Registry API"): The OpenAPI specification defined in [openapi.yaml](./server-registry-api/openapi.yaml). This is a reusable API specification that anyone building any sort of "MCP server registry" should consider adopting / aligning with.
 - "Official MCP Registry" (or "MCP Registry"): The application that lives at `https://registry.modelcontextprotocol.io`. This registry currently only catalogs MCP servers, but may be extended in the future to also catalog MCP client/host apps and frameworks.
-- "Official MCP Registry API": The REST API that lives at `https://registry.modelcontextprotocol.io/api`, with an OpenAPI specification defined at [official-registry-openapi.yaml](./server-registry-api/official-registry-openapi.yaml)
+- "Official MCP Registry API": The REST API that lives at `https://registry.modelcontextprotocol.io/api`, with an OpenAPI specification defined at [swagger.yaml](../internal/docs/swagger.yaml)
 - "MCP server registry" (or "MCP registry"): A third party, likely commercial, implementation of the MCP Server Registry API or derivative specification.
 
 ### Is the MCP Registry a package registry?

docs/server-registry-api/README.md

@@ -10,5 +10,4 @@ The centralized, publicly available catalog ("Official MCP Registry") needs addi
 
 References:
 - [openapi.yaml](./openapi.yaml) - A reusable API specification (MCP Server Registry API) that anyone building any sort of "MCP server registry" should consider adopting / aligning with.
-- [examples.md](./api_examples.md) - Example manifestations of the OpenAPI specification
-- [official-registry-openapi.ayml](./official-registry-openapi.yaml) - The specification backing the Official MCP Registry; a derivative of the MCP Server Registry API specification.
+- [swagger.yaml](../../internal/docs/swagger.yaml) - The specification backing the Official MCP Registry; a derivative of the MCP Server Registry API specification.