Add Swagger API documentation and handlers for v0
This commit is contained in:
Avinash Sridhar
parent
4c401c0b25
commit
39bcae1c81
3 changed files with 275 additions and 0 deletions
45
internal/api/handlers/v0/swagger.go
Normal file
45
internal/api/handlers/v0/swagger.go
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
// Package v0 contains API handlers for version 0 of the API
|
||||
package v0
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"os"
|
||||
"path/filepath"
|
||||
|
||||
_ "github.com/swaggo/files"
|
||||
httpSwagger "github.com/swaggo/http-swagger"
|
||||
)
|
||||
|
||||
// SwaggerHandler returns a handler that serves the Swagger UI
|
||||
func SwaggerHandler() http.HandlerFunc {
|
||||
return func(w http.ResponseWriter, r *http.Request) {
|
||||
// When accessed directly, redirect to the UI path
|
||||
if r.URL.Path == "/v0/swagger" {
|
||||
http.Redirect(w, r, "/v0/swagger/", http.StatusFound)
|
||||
return
|
||||
}
|
||||
|
||||
// Serve the Swagger UI
|
||||
handler := httpSwagger.Handler(
|
||||
httpSwagger.URL("/v0/swagger/doc.json"), // The URL to the generated Swagger JSON
|
||||
httpSwagger.DeepLinking(true),
|
||||
)
|
||||
|
||||
// Handle other Swagger UI paths
|
||||
handler.ServeHTTP(w, r)
|
||||
}
|
||||
}
|
||||
|
||||
// SwaggerJSONHandler serves the Swagger specification as JSON
|
||||
func SwaggerJSONHandler() http.HandlerFunc {
|
||||
return func(w http.ResponseWriter, r *http.Request) {
|
||||
// Find the project root directory
|
||||
workDir, _ := os.Getwd()
|
||||
|
||||
// Path to the swagger YAML file
|
||||
swaggerFilePath := filepath.Join(workDir, "internal", "docs", "swagger.yaml")
|
||||
|
||||
// Serve the file directly with the correct content type
|
||||
http.ServeFile(w, r, swaggerFilePath)
|
||||
}
|
||||
}
|
||||
|
|
@ -16,4 +16,8 @@ func RegisterV0Routes(mux *http.ServeMux, cfg *config.Config, registry service.R
|
|||
mux.HandleFunc("/v0/servers", v0.ServersHandler(registry))
|
||||
mux.HandleFunc("/v0/servers/{id}", v0.ServersDetailHandler(registry))
|
||||
mux.HandleFunc("/v0/ping", v0.PingHandler(cfg))
|
||||
|
||||
// Register Swagger UI routes
|
||||
mux.HandleFunc("/v0/swagger/", v0.SwaggerHandler())
|
||||
mux.HandleFunc("/v0/swagger/doc.json", v0.SwaggerJSONHandler())
|
||||
}
|
||||
|
|
|
|||
168
internal/docs/swagger.yaml
Normal file
168
internal/docs/swagger.yaml
Normal file
|
|
@ -0,0 +1,168 @@
|
|||
openapi: 3.0.0
|
||||
info:
|
||||
title: Model Context Protocol Registry API
|
||||
description: API for the Model Context Protocol Registry
|
||||
version: "0.1.0"
|
||||
|
||||
servers:
|
||||
- url: /
|
||||
description: Default server
|
||||
|
||||
tags:
|
||||
- name: health
|
||||
description: Health checking operations
|
||||
- name: servers
|
||||
description: Server registry operations
|
||||
|
||||
paths:
|
||||
/v0/health:
|
||||
get:
|
||||
tags:
|
||||
- health
|
||||
summary: Health check endpoint
|
||||
description: Returns the health status of the API
|
||||
operationId: healthCheck
|
||||
responses:
|
||||
'200':
|
||||
description: Successful operation
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
example: ok
|
||||
|
||||
/v0/ping:
|
||||
get:
|
||||
tags:
|
||||
- health
|
||||
summary: API version check
|
||||
description: Returns the API version and status
|
||||
operationId: pingCheck
|
||||
responses:
|
||||
'200':
|
||||
description: Successful operation
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
example: ok
|
||||
version:
|
||||
type: string
|
||||
example: "0.1.0"
|
||||
'405':
|
||||
description: Method not allowed
|
||||
|
||||
/v0/servers:
|
||||
get:
|
||||
tags:
|
||||
- servers
|
||||
summary: List registered servers
|
||||
description: Returns a paginated list of registered servers
|
||||
operationId: listServers
|
||||
parameters:
|
||||
- name: cursor
|
||||
in: query
|
||||
description: Pagination cursor (UUID)
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
- name: limit
|
||||
in: query
|
||||
description: Maximum number of items to return (1-100, default 30)
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
default: 30
|
||||
responses:
|
||||
'200':
|
||||
description: Successful operation
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
servers:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Server'
|
||||
metadata:
|
||||
$ref: '#/components/schemas/PaginationMetadata'
|
||||
'400':
|
||||
description: Invalid cursor or limit parameter
|
||||
'405':
|
||||
description: Method not allowed
|
||||
|
||||
/v0/servers/{id}:
|
||||
get:
|
||||
tags:
|
||||
- servers
|
||||
summary: Get server details
|
||||
description: Returns details of a specific server by ID
|
||||
operationId: getServerDetails
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
description: Server ID (UUID)
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
responses:
|
||||
'200':
|
||||
description: Successful operation
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Server'
|
||||
'400':
|
||||
description: Invalid ID format
|
||||
'404':
|
||||
description: Server not found
|
||||
'405':
|
||||
description: Method not allowed
|
||||
|
||||
components:
|
||||
schemas:
|
||||
Server:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "123e4567-e89b-12d3-a456-426614174000"
|
||||
name:
|
||||
type: string
|
||||
example: "Example MCP Server"
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
example: "https://example.com/mcp"
|
||||
description:
|
||||
type: string
|
||||
example: "An example MCP server"
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
PaginationMetadata:
|
||||
type: object
|
||||
properties:
|
||||
next_cursor:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "123e4567-e89b-12d3-a456-426614174000"
|
||||
count:
|
||||
type: integer
|
||||
example: 30
|
||||
Loading…
Reference in a new issue