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:
// @Param body body MyRequest true "request payload"the generated requestBody.content["application/json"].schema is emitted as:
{ "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/MyRequest", "description": "request payload" } ] }instead of the expected plain:
{ "$ref": "#/components/schemas/MyRequest" }This causes two separate problems downstream:
- The
$refsibling (descriptionnext to$ref) is invalid per OAS 3.0 ($refsiblings are ignored/disallowed) and rejected by strict validators like kin-openapi even under 3.1. - Because it's a genuine 2-branch
oneOfrather than a single reference,openapi-generatorcan't dedupe it back to the named schema — it synthesizes a throwaway per-operation wrapper model (e.g.my_operation_request.py) instead of reusingMyRequest, 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.
Source: swaggo/swag