Inline response bodies

The Routes & operations tutorial declares each response as a swagger:response struct with a Body field. That is the right tool when a response is reused across operations or has headers. But when a response body is just “a string”, “an array of Pet”, or “a Pet”, the wrapper struct is pure boilerplate.

The Responses: block of a swagger:route accepts the body: sub-language, which names the body shape directly:

body:string (or number / integer / boolean) — a primitive body;
body:Pet — a $ref to the Pet definition;
body:[]Pet — an array of that $ref (repeat [] to nest deeper);
any trailing words after the body token become the response description; omit them and codescan derives one — the referenced model’s godoc (default above → the Pet doc comment), or the HTTP status reason for a numeric code (400 above → “Bad Request”).

swagger:route

// swagger:route GET /pets pets listPets
//
// Lists pets. Each response is declared inline with the body: sub-language — a
// primitive, an array of a model, or a single model $ref — so no wrapper
// response type is needed. Trailing words become the response description; omit
// them and codescan derives one (the model's godoc, or the HTTP status reason).
//
//	Responses:
//	  200: body:[]Pet the list of pets
//	  400: body:string
//	  default: body:Pet

Full source: docs/examples/shaping/inlineresponses/inlineresponses.go

paths[/pets]

{
  "get": {
    "description": "Lists pets. Each response is declared inline with the body: sub-language — a\nprimitive, an array of a model, or a single model $ref — so no wrapper\nresponse type is needed. Trailing words become the response description; omit\nthem and codescan derives one (the model's godoc, or the HTTP status reason).",
    "tags": [
      "pets"
    ],
    "operationId": "listPets",
    "responses": {
      "200": {
        "description": "the list of pets",
        "schema": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Pet"
          }
        }
      },
      "400": {
        "description": "Bad Request",
        "schema": {
          "type": "string"
        }
      },
      "default": {
        "description": "Pet is the model the inline responses reference.",
        "schema": {
          "$ref": "#/definitions/Pet"
        }
      }
    }
  }
}

Full source: docs/examples/shaping/inlineresponses/testdata/pathitem.json

No swagger:response struct is defined — the three responses are produced entirely from the body: tokens, and the Pet model is pulled into definitions because the body $refs reach it.

Info

A bare untagged token is read as a response name, never a type: 200: string is a (dangling) $ref to a response called string, not a primitive body. Use the explicit body:string form for a primitive. The full grammar — tags, untagged-token rules, and the reserved array/object/file keywords — is in sub-languages → Responses.