英文:
springdoc-openapi different examples
问题
使用springdoc-openapi来记录我的REST API。一个错误是通过一个错误对象返回的,该对象具有errorCode
和message
。我使用@Schema
注解来记录一个示例。然而,我需要针对不同的错误提供不同的示例。是否有任何方法可以实现这一点?
我的代码示例:
@PostMapping(consumes = APPLICATION_JSON_VALUE, produces = APPLICATION_JSON_VALUE)
@Operation(summary = "获取新许可证或检索先前为此userId发放的许可证。", tags = "许可证终端点", description = "许可证操作。",
responses = {
@ApiResponse(
responseCode = "200",
description = "为该用户获取新许可证或先前发放的许可证,如果多次调用请求。",
content = {@Content(schema = @Schema(implementation = LicenseResponse.class))}
),
@ApiResponse(responseCode = "400",
description = "由于过期的bundle或请求的bundleId不存在,无法检索许可证。",
//我需要为此错误提供不同的示例
content = {@Content(schema = @Schema(implementation = LicenseErrorResponse.class))}
),
@ApiResponse(responseCode = "500",
description = "内部错误",
//以及为此错误提供不同的示例
content = {@Content(schema = @Schema(implementation = LicenseErrorResponse.class))}
)
}
)
@LoggedIO(input = INFO, result = INFO)
public ResponseEntity<Object> newLicense(@Valid @RequestBody LicenseRequest licenseRequest) {
//内容不重要
}
import javax.validation.constraints.NotBlank;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
@Data
public class LicenseErrorResponse {
// 我需要为控制器中的不同错误提供不同的示例。
@Schema(example = "UNKNOWN_BUNDLE_ID", required = true)
private final LicenseErrorCode licenseErrorCode;
@Schema(example = "Bundle不存在,bundleId=com.unknown.id")
private final String message;
@JsonCreator
public LicenseErrorResponse(
@NotBlank @JsonProperty(value = "errorCode") final LicenseErrorCode licenseErrorCode,
@NotBlank @JsonProperty(value = "message") final String message) {
this.licenseErrorCode = licenseErrorCode;
this.message = message;
}
public enum LicenseErrorCode {
EXPIRED_BUNDLE, UNKNOWN_BUNDLE_ID, OTHER
}
}
英文:
I use springdoc-openapi to document my REST API. An error is returned by an error object, that has an errorCode
and message
. I use @Schema
annotation to document an example. However I need different examples per different errors. Is there any way, how to do that?
Example from my code:
@PostMapping(consumes = APPLICATION_JSON_VALUE, produces = APPLICATION_JSON_VALUE)
@Operation(summary = "Get new license or retrieve previously issued one for this userId.", tags = "License Endpoint", description = "Licensing operations.",
responses = {
@ApiResponse(
responseCode = "200",
description = "New license or previously issued license for this user, if request was called multiple times.",
content = {@Content(schema = @Schema(implementation = LicenseResponse.class))}
),
@ApiResponse(responseCode = "400",
description = "License can not be retrieved because of either expired bundle or requested bundleId does not exist.",
//I need different example for this error
content = {@Content(schema = @Schema(implementation = LicenseErrorResponse.class))
}
),
@ApiResponse(responseCode = "500",
description = "Internal Error",
//And different example for this error
content = {@Content(schema = @Schema(implementation = LicenseErrorResponse.class))
}
)
}
)
@LoggedIO(input = INFO, result = INFO)
public ResponseEntity<Object> newLicense(@Valid @RequestBody LicenseRequest licenseRequest) {
//content not interesting
}
import javax.validation.constraints.NotBlank;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
@Data
public class LicenseErrorResponse {
// I need different examples for different error in controller.
@Schema(example = "UNKNOWN_BUNDLE_ID", required = true)
private final LicenseErrorCode licenseErrorCode;
@Schema(example = "Bundle doesn't exist, bundleId=com.unknown.id")
private final String message;
@JsonCreator
public LicenseErrorResponse(
@NotBlank @JsonProperty(value = "errorCode") final LicenseErrorCode licenseErrorCode,
@NotBlank @JsonProperty(value = "message") final String message) {
this.licenseErrorCode = licenseErrorCode;
this.message = message;
}
public enum LicenseErrorCode {
EXPIRED_BUNDLE, UNKNOWN_BUNDLE_ID, OTHER
}
}
答案1
得分: 2
public static final String exampleInternalError = "{\r\n"
+ " \"licenseErrorCode\": 500,\r\n"
+ " \"message\": \"Internal Error\"\r\n" + "}";
@ApiResponse(responseCode = "500",
description = "Internal Error",
//And different example for this error
content = @Content(schema = @Schema(implementation = LicenseErrorResponse.class),
examples = @ExampleObject(description = "Internal Error", value = exampleInternalError)))
英文:
One way to do that is you can define a string as an example
public static final String exampleInternalError = "{\r\n"
+ " \"licenseErrorCode\": 500,\r\n"
+ " \"message\": \"Internal Error\"\r\n" + "}";
same is used to show the example as
@ApiResponse(responseCode = "500",
description = "Internal Error",
//And different example for this error
content = @Content(schema = @Schema(implementation = LicenseErrorResponse.class),
examples = @ExampleObject(description = "Internal Error", value = exampleInternalError)))
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库,让每个人都能够通过互相帮助和分享经验来进步。
评论