springdoc-openapi 不同的示例

huangapple go评论113阅读模式
英文:

springdoc-openapi different examples

问题

使用springdoc-openapi来记录我的REST API。一个错误是通过一个错误对象返回的,该对象具有errorCodemessage。我使用@Schema注解来记录一个示例。然而,我需要针对不同的错误提供不同的示例。是否有任何方法可以实现这一点?

我的代码示例:

  1. @PostMapping(consumes = APPLICATION_JSON_VALUE, produces = APPLICATION_JSON_VALUE)
  2. @Operation(summary = "获取新许可证或检索先前为此userId发放的许可证。", tags = "许可证终端点", description = "许可证操作。",
  3. responses = {
  4. @ApiResponse(
  5. responseCode = "200",
  6. description = "为该用户获取新许可证或先前发放的许可证,如果多次调用请求。",
  7. content = {@Content(schema = @Schema(implementation = LicenseResponse.class))}
  8. ),
  9. @ApiResponse(responseCode = "400",
  10. description = "由于过期的bundle或请求的bundleId不存在,无法检索许可证。",
  11. //我需要为此错误提供不同的示例
  12. content = {@Content(schema = @Schema(implementation = LicenseErrorResponse.class))}
  13. ),
  14. @ApiResponse(responseCode = "500",
  15. description = "内部错误",
  16. //以及为此错误提供不同的示例
  17. content = {@Content(schema = @Schema(implementation = LicenseErrorResponse.class))}
  18. )
  19. }
  20. )
  21. @LoggedIO(input = INFO, result = INFO)
  22. public ResponseEntity<Object> newLicense(@Valid @RequestBody LicenseRequest licenseRequest) {
  23. //内容不重要
  24. }
  1. import javax.validation.constraints.NotBlank;
  2. import com.fasterxml.jackson.annotation.JsonCreator;
  3. import com.fasterxml.jackson.annotation.JsonProperty;
  4. import io.swagger.v3.oas.annotations.media.Schema;
  5. import lombok.Data;
  6. @Data
  7. public class LicenseErrorResponse {
  8. // 我需要为控制器中的不同错误提供不同的示例。
  9. @Schema(example = "UNKNOWN_BUNDLE_ID", required = true)
  10. private final LicenseErrorCode licenseErrorCode;
  11. @Schema(example = "Bundle不存在,bundleId=com.unknown.id")
  12. private final String message;
  13. @JsonCreator
  14. public LicenseErrorResponse(
  15. @NotBlank @JsonProperty(value = "errorCode") final LicenseErrorCode licenseErrorCode,
  16. @NotBlank @JsonProperty(value = "message") final String message) {
  17. this.licenseErrorCode = licenseErrorCode;
  18. this.message = message;
  19. }
  20. public enum LicenseErrorCode {
  21. EXPIRED_BUNDLE, UNKNOWN_BUNDLE_ID, OTHER
  22. }
  23. }
英文:

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:

  1. @PostMapping(consumes = APPLICATION_JSON_VALUE, produces = APPLICATION_JSON_VALUE)
  2. @Operation(summary = &quot;Get new license or retrieve previously issued one for this userId.&quot;, tags = &quot;License Endpoint&quot;, description = &quot;Licensing operations.&quot;,
  3. responses = {
  4. @ApiResponse(
  5. responseCode = &quot;200&quot;,
  6. description = &quot;New license or previously issued license for this user, if request was called multiple times.&quot;,
  7. content = {@Content(schema = @Schema(implementation = LicenseResponse.class))}
  8. ),
  9. @ApiResponse(responseCode = &quot;400&quot;,
  10. description = &quot;License can not be retrieved because of either expired bundle or requested bundleId does not exist.&quot;,
  11. //I need different example for this error
  12. content = {@Content(schema = @Schema(implementation = LicenseErrorResponse.class))
  13. }
  14. ),
  15. @ApiResponse(responseCode = &quot;500&quot;,
  16. description = &quot;Internal Error&quot;,
  17. //And different example for this error
  18. content = {@Content(schema = @Schema(implementation = LicenseErrorResponse.class))
  19. }
  20. )
  21. }
  22. )
  23. @LoggedIO(input = INFO, result = INFO)
  24. public ResponseEntity&lt;Object&gt; newLicense(@Valid @RequestBody LicenseRequest licenseRequest) {
  25. //content not interesting
  26. }
  1. import javax.validation.constraints.NotBlank;
  2. import com.fasterxml.jackson.annotation.JsonCreator;
  3. import com.fasterxml.jackson.annotation.JsonProperty;
  4. import io.swagger.v3.oas.annotations.media.Schema;
  5. import lombok.Data;
  6. @Data
  7. public class LicenseErrorResponse {
  8. // I need different examples for different error in controller.
  9. @Schema(example = &quot;UNKNOWN_BUNDLE_ID&quot;, required = true)
  10. private final LicenseErrorCode licenseErrorCode;
  11. @Schema(example = &quot;Bundle doesn&#39;t exist, bundleId=com.unknown.id&quot;)
  12. private final String message;
  13. @JsonCreator
  14. public LicenseErrorResponse(
  15. @NotBlank @JsonProperty(value = &quot;errorCode&quot;) final LicenseErrorCode licenseErrorCode,
  16. @NotBlank @JsonProperty(value = &quot;message&quot;) final String message) {
  17. this.licenseErrorCode = licenseErrorCode;
  18. this.message = message;
  19. }
  20. public enum LicenseErrorCode {
  21. EXPIRED_BUNDLE, UNKNOWN_BUNDLE_ID, OTHER
  22. }
  23. }

答案1

得分: 2

  1. public static final String exampleInternalError = "{\r\n"
  2. + " \"licenseErrorCode\": 500,\r\n"
  3. + " \"message\": \"Internal Error\"\r\n" + "}";
  1. @ApiResponse(responseCode = "500",
  2. description = "Internal Error",
  3. //And different example for this error
  4. content = @Content(schema = @Schema(implementation = LicenseErrorResponse.class),
  5. examples = @ExampleObject(description = "Internal Error", value = exampleInternalError)))
英文:

One way to do that is you can define a string as an example

  1. public static final String exampleInternalError = &quot;{\r\n&quot;
  2. + &quot; \&quot;licenseErrorCode\&quot;: 500,\r\n&quot;
  3. + &quot; \&quot;message\&quot;: \&quot;Internal Error\&quot;\r\n&quot; + &quot;}&quot;;

same is used to show the example as

  1. @ApiResponse(responseCode = &quot;500&quot;,
  2. description = &quot;Internal Error&quot;,
  3. //And different example for this error
  4. content = @Content(schema = @Schema(implementation = LicenseErrorResponse.class),
  5. examples = @ExampleObject(description = &quot;Internal Error&quot;, value = exampleInternalError)))

huangapple
  • 本文由 发表于 2020年4月6日 00:08:02
  • 转载请务必保留本文链接:https://go.coder-hub.com/61045499.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定