@ApiResponse 響應體為空（Spring Boot）

Question

我正在尋找一種方法來告訴 swagger 某個 API 響應代碼沒有響應主體。 例如，get 響應可以返回帶有實際 object 的 200 代碼作為響應，或者如果與傳遞的 ID 關聯的 object 不存在則返回 404：

@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Object found"),
    @ApiResponse(responseCode = "404", description = "Invalid object ID", content = @Content)
})

這是我能想到的最接近的東西，但它並不完美，在 404 響應的描述下我仍然得到一個煩人的“媒體類型”。 謝謝！

Answer 1

如果您沒有指定@ApiResponse注釋的content屬性，則控制器方法的返回類型將是您的響應內容。 為了防止這種情況，明確定義content ：

@ApiResponse(responseCode = "200", description = "OK",
             content = @Content(schema = @Schema(implementation = Void.class)))

或者您可以簡單地返回ResponseEntity<Void> 。

Answer 2

您可以在 v2 中的方法之上使用以下內容

@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Success", response = YourObject.class),
        @ApiResponse(code = 401, message = "Unauthorized"),
        @ApiResponse(code = 403, message="Forbidden"),
        @ApiResponse(code = 404, message = "Not Found"),
        @ApiResponse(code = 500, message = "Failure")
})

對於 V3，您可以嘗試這樣的方法，以防您的方法返回某個對象

@Operation(summary = "Add a new object", description = "", tags = { "yourObject" })
@ApiResponses(value = { 
        @ApiResponse(responseCode = "201", description = "Object created",content = @Content(schema = @Schema(implementation = YourObject.class))), 
        @ApiResponse(responseCode = "400", description = "Invalid input"), 
        @ApiResponse(responseCode = "409", description = "Object already exists") })    
        @PostMapping(value = "/your-url", consumes = {"application/json","application/xml" })
        public ResponseEntity<YourObject> addObject(
            ...
            return ...
        }

如果你的方法返回 void 試試這個

@Operation(summary = "Update an existing object", description = "", tags = { "yourObject" })
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "successful operation"),
        @ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
        @ApiResponse(responseCode = "404", description = "Object not found"),
        @ApiResponse(responseCode = "405", description = "Validation exception") })  
        @PutMapping(value = "/your-url/{id}", consumes = { "application/json", "application/xml" })  
        public ResponseEntity<Void> addObject(
            ...
            return ...
        }

Answer 3

這可能是更好（也更短）的方式：

@ApiResponse(
   responseCode = "404", 
   description = "Not found", 
   content = @Content(schema = @Schema(hidden = true))) 

Answer 4

不確定它是否是一項功能，但空的@Content對我有用：

interface MyControllerOpenApiSpec {

    @ApiResponse(responseCode = "200") // shows MyDTO schema
    @ApiResponse(responseCode = "404", content = @Content) // no schema shown
    MyDTO getMyDTO();

}

Answer 5

沒有任何內容方法； 也許，它被改變了。

public @interface ApiResponse {
    int code();

    String message();

    Class<?> response() default Void.class;

    String reference() default "";

    ResponseHeader[] responseHeaders() default {@ResponseHeader(
    name = "",
    response = Void.class
)};

    String responseContainer() default "";

    Example examples() default @Example({@ExampleProperty(
    value = "",
    mediaType = ""
)});
}