#2197·swag

v2: every @Param body request body wrapped in a spurious 2-branch oneOf with a $ref sibling

Author: ahridinCreated Jul 14, 2026Updated Aug 5, 2026

swag version: v2.0.0-rc5

For a simple, single-type request body:

go
// @Param body body MyRequest true "request payload"

the generated requestBody.content["application/json"].schema is emitted as:

json
{ "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/MyRequest", "description": "request payload" } ] }

instead of the expected plain:

json
{ "$ref": "#/components/schemas/MyRequest" }

This causes two separate problems downstream:

  1. The $ref sibling (description next to $ref) is invalid per OAS 3.0 ($ref siblings are ignored/disallowed) and rejected by strict validators like kin-openapi even under 3.1.
  2. Because it's a genuine 2-branch oneOf rather than a single reference, openapi-generator can't dedupe it back to the named schema — it synthesizes a throwaway per-operation wrapper model (e.g. my_operation_request.py) instead of reusing MyRequest, for every single endpoint with a body parameter.

Expected: a single-type @Param body should emit a plain $ref to the schema, not a 2-branch oneOf.