Is it possible to generate OpenApi doc with request body content for GET operation?

[andyholst]

Hi, my general problem is that my @RequestBody argument gets generated as parameters list instead (with POST/PUT it gets generated with request body content as supposed to), if I replace the parameters list with my request body content instead so I can execute the content with following curl command below, it works just fine.

curl -X GET "http://localhost:8080/api/get/client/info/" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"personIdentificationNumber\":\"191212121212\"}"

Is there something I am doing wrong? The
RFC 7231 specification states that

A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some existing implementations to reject the request.

So it should be possible. If I am not doing anything wrong with my GET code operation below, will it be possible to generate request body content for GET RESTul operation in the future?

For my following @GetMapping operation I have the following:

    @GetMapping(value = "/get/client/info/", consumes = {MediaType.APPLICATION_JSON_VALUE}, produces =
            {MediaType.APPLICATION_JSON_VALUE})
    @Operation(summary = "Get client by client request body",
            description = "Get the ClientAPI response object with uniqueue personal identification number as " +
                    "part of the request body.",
            responses = {
                    @ApiResponse(responseCode = "200",
                            description = "The client", content = @Content(mediaType =
                            MediaType.APPLICATION_JSON_VALUE,
                            schema = @Schema(implementation = ClientApi.class))),
                    @ApiResponse(responseCode = "400",
                            description = "Invalid personal identification number", content = @Content(mediaType =
                            MediaType.TEXT_PLAIN_VALUE,
                            schema = @Schema(example = "Invalid personal identification number."))),
                    @ApiResponse(responseCode = "404",
                            description = "Client not found.", content = @Content(mediaType =
                            MediaType.TEXT_PLAIN_VALUE,
                            schema = @Schema(example = "Client not found."))),
                    @ApiResponse(responseCode = "500", description = "Severe system failure has occured!", content =
                    @Content(mediaType = MediaType.TEXT_PLAIN_VALUE, schema = @Schema(
                            example = "Severe system failure has occured!")))})
    public ResponseEntity<ClientApi> getClientInformationByRequestBody(
            @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "ClientRequest body.",
                    content = @Content(schema = @Schema(implementation = ClientRequest.class)), required = true)
            @ClientRequestBodyConstraint
            @RequestBody ClientRequest clientRequest) {
        ClientApi clientApi = openBankService.getClientInformationByPersonIdentification(clientRequest
                .getPersonIdentificationNumber());

        if (clientApi == null) {
            throw new ClientNotFoundException("Client not found.");
        }

         return ResponseEntity.ok(clientApi);
    }

The generated OpenApi GET operation content gets generated as:

/api/get/client/info/:
    get:
      summary: Get client by client request body
      description: Get the ClientAPI response object with uniqueue personal identification
        number as part of the request body.
      operationId: getClientInformationByRequestBody
      parameters:
      - name: clientRequest
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/ClientRequest'
      responses:
        200:
          description: The client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientApi'
        400:
          description: Invalid personal identification number
          content:
            text/plain:
              schema:
                type: string
                example: Invalid personal identification number.
        404:
          description: Client not found.
          content:
            text/plain:
              schema:
                type: string
                example: Client not found.
        500:
          description: Severe system failure has occured!
          content:
            text/plain:
              schema:
                type: string
                example: Severe system failure has occured!

Hi,

The behaviour that you are describing is normal with OpenAPI 3.
GET, DELETE and HEAD are no longer allowed to have request body because they does not have defined semantics as per RFC 7231.

Here is another reference, from the swagger official website about it:

• https://swagger.io/docs/specification/describing-request-body/

[andyholst]

I was able to generate the OpenApi specification by defining the RequestBody for GET operation and hide the Parameter list at argument method level for the RequestBody.

 @GetMapping(value = "/get/client/info/", consumes = {MediaType.APPLICATION_JSON_VALUE}, produces =
            {MediaType.APPLICATION_JSON_VALUE})
    @Operation(summary = "Get client by client request body",
            requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "ClientRequest body.",
                    content = @Content(schema = @Schema(implementation = ClientRequest.class)), required = true),
            description = "Get the ClientAPI response object with uniqueue personal identification number as " +
                    "part of the request body.",
            responses = {
                    @ApiResponse(responseCode = "200",
                            description = "The client", content = @Content(mediaType =
                            MediaType.APPLICATION_JSON_VALUE,
                            schema = @Schema(implementation = ClientApi.class))),
                    @ApiResponse(responseCode = "400",
                            description = "Invalid personal identification number", content = @Content(mediaType =
                            MediaType.TEXT_PLAIN_VALUE,
                            schema = @Schema(example = "Invalid personal identification number."))),
                    @ApiResponse(responseCode = "404",
                            description = "Client not found.", content = @Content(mediaType =
                            MediaType.TEXT_PLAIN_VALUE,
                            schema = @Schema(example = "Client not found."))),
                    @ApiResponse(responseCode = "500", description = "Severe system failure has occured!", content =
                    @Content(mediaType = MediaType.TEXT_PLAIN_VALUE, schema = @Schema(
                            example = "Severe system failure has occured!")))})
    public ResponseEntity<ClientApi> getClientInformationByRequestBody(@Parameter(hidden = true) 
                                                                           @ClientRequestBodyConstraint
            @RequestBody ClientRequest clientRequest) {
        ClientApi clientApi = openBankService.getClientInformationByPersonIdentification(clientRequest
                .getPersonIdentificationNumber());

        if (clientApi == null) {
            throw new ClientNotFoundException("Client not found.");
        }

        return ResponseEntity.ok(clientApi);
    }

[anderdev]

I was able to generate the OpenApi specification by defining the RequestBody for GET operation and hide the Parameter list at argument method level for the RequestBody.

 @GetMapping(value = "/get/client/info/", consumes = {MediaType.APPLICATION_JSON_VALUE}, produces =
            {MediaType.APPLICATION_JSON_VALUE})
    @Operation(summary = "Get client by client request body",
            requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "ClientRequest body.",
                    content = @Content(schema = @Schema(implementation = ClientRequest.class)), required = true),
            description = "Get the ClientAPI response object with uniqueue personal identification number as " +
                    "part of the request body.",
            responses = {
                    @ApiResponse(responseCode = "200",
                            description = "The client", content = @Content(mediaType =
                            MediaType.APPLICATION_JSON_VALUE,
                            schema = @Schema(implementation = ClientApi.class))),
                    @ApiResponse(responseCode = "400",
                            description = "Invalid personal identification number", content = @Content(mediaType =
                            MediaType.TEXT_PLAIN_VALUE,
                            schema = @Schema(example = "Invalid personal identification number."))),
                    @ApiResponse(responseCode = "404",
                            description = "Client not found.", content = @Content(mediaType =
                            MediaType.TEXT_PLAIN_VALUE,
                            schema = @Schema(example = "Client not found."))),
                    @ApiResponse(responseCode = "500", description = "Severe system failure has occured!", content =
                    @Content(mediaType = MediaType.TEXT_PLAIN_VALUE, schema = @Schema(
                            example = "Severe system failure has occured!")))})
    public ResponseEntity<ClientApi> getClientInformationByRequestBody(@Parameter(hidden = true) 
                                                                           @ClientRequestBodyConstraint
            @RequestBody ClientRequest clientRequest) {
        ClientApi clientApi = openBankService.getClientInformationByPersonIdentification(clientRequest
                .getPersonIdentificationNumber());

        if (clientApi == null) {
            throw new ClientNotFoundException("Client not found.");
        }

        return ResponseEntity.ok(clientApi);
    }

hi buddy,

I kinda have the same situation, but my request body is an Object instead of ClientRequest clientRequest, happens that then Springdoc does not generate the request body in the API definition.

Am I doing something wrong?