将 Swagger 文档用于 HttpServletRequest

Question

我不熟悉 swagger 和使用它的文档。我目前正在尝试使用 swagger 来显示 PATCH 请求的请求正文。之前PATCH方法的参数是更新对象的DTO，这样可以很方便的显示对象的属性（我用的是SpringBoot，用@Schema就完美了）。但是，现在 PATCH 方法的参数是一个 HttpServletRequest。我不想在 swagger 文档中显示 HttpServletRequest（这似乎是自动发生的），而是想显示 DTO 属性（就像之前所做的那样）。我想知道是否有办法做到这一点？

非常感谢任何建议！

Answer 1

我假设您正在使用 springdoc-openapi 生成 SwaggerUI。

要使用它，您可以使用以下 Maven 依赖项，

<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>

从 springdoc-openapi 的 v1.1.25 开始，HttpServletRequest 和 HttpServletResponse 将被添加到忽略的类型列表中。

见下文，

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

所以即使我们在controller方法内部添加HttpServletRequest作为参数，也会被忽略，不会在swagger中显示出来

所以回到你的问题，要显示一个class的模型，你可以描述另一个参数连同 HttpServletRequest 如下，

@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"));

Auth2的模型class如下，可以描述你的用户名和密码等示例值

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;

}

最终 swagger 页面如下所示，

当您在授权中输入内容时header，如下，

这可以通过以下代码通过 HTTP servlet 请求访问，

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

springboot 应用程序中的日志条目如下所示，

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

Answer 2

上述答案无效，因为向该方法添加另一个参数会破坏该方法本身的功能。

有效的解决方案是在控制器中将内容参数添加到 @RequestBody 注释：

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

Answer 3

How to displaying the HttpServletRequest in the swagger doc?

可以在swagger2的配置中设置，SwaggerConfig.java

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

将 Swagger 文档用于 HttpServletRequest

Using Swagger Documentation for HttpServletRequest

java

servlets

swagger

spring-boot

swagger-codegen