使用 HttpServletRequest 的 Swagger 文档

Question

I am new to swagger and using it's documentation. I am currently trying to use swagger to display the request body of a PATCH request. Previously, the parameter of the PATCH method was the DTO of the object that was being updated, which made it very easy to display the attributes of the object (as I am using SpringBoot, and using @Schema worked perfectly). However, now the parameter of the PATCH method is an HttpServletRequest. Instead of displaying the HttpServletRequest in the swagger doc (which seems to automatically be happening), I want to show the DTOs attributes (just as had been done before). I was wondering if there was a way to do that?

Any advice is much appreciated!

Answer 1

I am assuming you are using springdoc-openapi for generating SwaggerUI.

To use this you can use the below Maven dependencies,

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.4.2</version>
</dependency>
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-webmvc-core</artifactId>
  <version>1.4.2</version>
</dependency>

From v1.1.25 of springdoc-openapi, HttpServletRequest and HttpServletResponse will be added to the list of ignored types.

See below,

https://github.com/springdoc/springdoc-openapi/issues/57

So even if we add HttpServletRequest as a parameter inside the controller method, it will be ignored and will not be displayed in the swagger.

So coming back to your question, to display the model of a class, you can describe another parameter along with HttpServletRequest as below,

@Operation(summary = "Returns a token", description = "Returns A token API", tags = "tokenGeneration", responses = {

            @ApiResponse(description = "Successful Operation", responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Timeresponse.class))),
            @ApiResponse(description = "not found Operation", responseCode = "404") })
    @PatchMapping("/getTokenPatchRequest")
    public ResponseEntity getTokenpatch(HttpServletRequest request, @RequestBody AuthReq2 req) {

        log.info("The HttpServlet request header contains the information : " + request.getHeader("Authorization"));

The model class of Auth2 is as below which can describe your example value of username and passwords etc.

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
public class AuthReq2 {
    
    @Schema(example = "diannamcallister")
    private String userName;
    
    @Schema(example = "test")
    private String password;

}

Ands finally the swagger page looks like this,

When you enter something in the authorization header, as below,

This can be accessed via the HTTP servlet request via the below code,

log.info("The HttpServlet request header contains the information : " + request.getHeader("Authorization"));

The log entry in the springboot application will look like below,

10:40:01.876 INFO   OpenApiController.getTokenpatch:163 - The HttpServlet request header contains the information : stackoverflow

Answer 2

The above answer did not work since adding another parameter to the method broke the functionality of the method itself.

The solution that worked was in the controller to add the content parameter to the @RequestBody annotation:

@RequestBody(description = "Description.", 
           content = @Content(schema = @Schema(implementation = ObjectDTO.class)));

Answer 3

How to displaying the HttpServletRequest in the swagger doc?

You can set in the configuration of swagger2, SwaggerConfig.java

new Docket(DocumentationType.SWAGGER_2)
                ...
                .ignoredParameterTypes(HttpSession.class, HttpServletRequest.class, HttpServletResponse.class)
                .build();