Schema generator add illegal request key under requestBody

[nbb-rhajdari]

We have a project that relies on nelmio doc bundle which in turn uses swagger-php. When we access our openapi doc.json, we suddenly receive a request key, that we did not have before, eg:

"requestBody": {
    "request": "ImageController",
    "description": "Replace product images.",
    "required": true,
    "content": {
        "application/json": {
            "schema": {
                "$ref": "#/components/schemas/ReplaceImageRequestDTO"
            }
        }
    }
},

As per the spec this key is illegal: https://spec.openapis.org/oas/latest.html#request-body-object

Field Name	Type	Description
description	string	A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content	Map[string, Media Type Object]	REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required	boolean	Determines if the request body is required in the request. Defaults to false.

This obviously leads to parsing errors, since the key is illegal:

Structural error at paths./api/images.put.requestBody
should NOT have additional properties
additionalProperty: request
Jump to line 438

Apparently this change comes from this PR: #1544

So am I right in the assumption that this is a bug or did I miss something?

[DerManoMann]

That would be a bug. However, hard to tell in conjunction with the bundle...

I've added some more variations to the request body scratch test #1640 The generated yaml looks ok to me; could you check if your attribute usage is covered by the test and if not post a sample so I can add it?

[nbb-rhajdari]

Maybe I am wrong but I believe the tests verify the bug, see here:
https://github.com/zircote/swagger-php/pull/1542/files#diff-7164864411da92d4ed3f6e3bc91a5cf78244180d7be5b15f2d1dc2765a5f194fR32

The Nelmio-Doc-Bundle uses a simple json_encode to create the json file:
https://github.com/nelmio/NelmioApiDocBundle/blob/master/src/Render/Json/JsonOpenApiRenderer.php#L35

And the OpenApi object holds this in fact before render:

JsonOpenApiRenderer.php on line 35:
OpenApi\Annotations\OpenApi {#2040 ▼
  ...
  +paths: array:16 [▼
    ...
    1 => OpenApi\Annotations\PathItem {#6582 ▼
      ...
      +put: OpenApi\Annotations\Put {#6882 ▼
        ...
        +requestBody: OpenApi\Annotations\RequestBody {#6950 ▼
          +x: "@OA\Generator::UNDEFINED🙈"
          +attachables: "@OA\Generator::UNDEFINED🙈"
          +_context: OpenApi\Context {#6929 …9}
          +_unmerged: []
          +ref: "@OA\Generator::UNDEFINED🙈"
          +request: "ImageController"
          +description: "Replace product images."
          +required: true
          +content: array:1 [ …1]
          _context: OpenApi\Context {#6929 …9}
          _unmerged: []
          request: "ImageController" <----------------------------
          description: "Replace product images."
          required: true
          content: array:1 [ …1]
        }
        ...
      }
      ...
    },
    ...
  ]
  ...
}

So either Nelmio should not just json_encode or swagger-php should not be adding this key?

[DerManoMann]

The annotations are written in a way that makes sense when using the library. The request property holds the name/key the request body is stored under in components.requestBodies.

If you look at the RequestBody annotation you'll find that the requestproperty is excluded from serialization:

    #[\ReturnTypeWillChange]
    public function jsonSerialize()
    {
        $data = parent::jsonSerialize();

        unset($data->request);

        return $data;
    }

This is implemented as \JsonSerializable, so I would expect this to apply to nested annotations too. First time I have heard about the serialization not working as expected.

is there any difference in calling $openapi->toJson() instead?

[DerManoMann]

Interestingly enough, this seems to be a duplicate of #1556 which was resolved via #1557.

Are you using the latest swagger-php version?

[nbb-rhajdari]

Sorry for the late reply, I have been absent for a while. You are absolutely right. We had been locked to 4.8.5, just one patch higher and we would have had the fix. Sorry for the confusion. I will close this issue :-)