go-openapi-docs-mesh-endpoints

Answer

Root cause: the server already wired the mesh routes at cmd/server/main.go:63-64 (/mesh/peers and /mesh/connect/), but the OpenAPI document never declared them — so the spec drifted from the running server.

Fix: add both paths to the spec, deriving every schema from the actual handler in internal/mesh/handler.go instead of inventing shapes. The two wire contracts, as observed from the handler:

• GET /mesh/peers → 200 with {"peers":[{"agent_id": "<id>"}], "count": <len(peers)>}
• GET /mesh/connect/{agentID} → 101 Switching Protocols on upgrade; 400 {"error": ...} when agentID is missing/blank (validation happens before the hijack); 405 on non-GET

Spec entries added under paths::

  /mesh/peers:
    get:
      operationId: meshPeers
      summary: List peer agents in the mesh
      tags: [mesh]
      responses:
        "200":
          description: Peer list. Body mirrors the JSON emitted by the live handler.
          content:
            application/json:
              schema:
                type: object
                required: [peers, count]          # both fields are always present
                properties:
                  peers:
                    type: array
                    items:
                      type: object
                      required: [agent_id]         # exact handler field name (snake_case)
                      properties:
                        agent_id: { type: string }
                  count:
                    type: integer
                    minimum: 0                     # always == len(peers)
        "405":
          description: Method not allowed (only GET is wired).
  /mesh/connect/{agentID}:
    get:
      operationId: meshConnect
      summary: Open a WebSocket connection to a peer agent
      parameters:
        - name: agentID
          in: path
          required: true
          schema: { type: string, minLength: 1 }
      responses:
        "101":                                    # WebSocket upgrade accepted
          description: Switching Protocols - WebSocket upgrade accepted.
        "400":                                    # rejected BEFORE any upgrade
          description: Missing or invalid agentID. The connection is NOT upgraded.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error: { type: string }
        "405":
          description: Method not allowed (only GET is wired).

The handler mirror (internal/mesh/handler.go shape, stdlib-only) that drives the verification:

func peersHandler(store map[string]string) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        if r.Method != http.MethodGet { w.WriteHeader(405); return }
        peers := make([]Peer, 0, len(store))      // non-nil so JSON is [], not null
        for id := range store { peers = append(peers, Peer{AgentID: id}) }
        json.NewEncoder(w).Encode(peersPayload{Peers: peers, Count: len(peers)})
    }
}
func connectHandler(store map[string]string) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        if r.Method != http.MethodGet { w.WriteHeader(405); return }
        agentID := strings.TrimSpace(strings.TrimPrefix(r.URL.Path, "/mesh/connect/"))
        if agentID == "" {                        // validate FIRST, then hijack
            w.WriteHeader(400); fmt.Fprint(w, `{"error":"agent_id required"}`); return
        }
        // ... WebSocket handshake -> 101 (see Evidence)
    }
}
// cmd/server/main.go:63-64
mux.HandleFunc("/mesh/peers", peersHandler(store))
mux.HandleFunc("/mesh/connect/", connectHandler(store))

Lesson applied (docs exception 3): never write spec entries from memory or guesses — read internal/mesh/handler.go first and copy its response shapes verbatim. Note the subtle details that surface only when reading code: count is redundant-but-always-present (not a schema invention), the peer key is agent_id (snake_case), the empty list is [] not null (so peers must be initialized non-nil), 400 fires before the upgrade attempt, and unknown-but-non-blank agentIDs still get 101 (presence validation only).