使用 Java 注释，有没有办法在其他模式中指定 Swagger/OpenAPI 模式？

Question

我试图使用Swagger UI来创建和部署我的文档以及我用Spring Boot编写的API。我知道Swagger提供了一些注释来帮助在实际的控制器类中编写文档，但是我很难让它们做我需要的事情。

我的问题是我有一个通用的DTO类，每次调用我的API都会返回。此 DTO 具有用于通用对象的内容字段。如果我直接使用这些对象，我知道我可以使用类似的东西

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

以便给出对象的JSON表示应该是什么样子的规范。但是，因为我将所有内容都包装在一个特定的< code>ResponseDTO类中，所以我需要一种方法来指定< code>contents字段应该是什么样子，并且我不确定可以使用哪些注释来完成这一点。我觉得绝对应该有类似

@ApiResponse(responseCode = "200", description = "Customer found",
    content = @Content(
        schema = @Schema(implementation = DTO.class, 
                         fields = { "contents" = @Schema(implementation = Customer.class)})))

或类似的东西。我无法找到如何真正实现这一目标的解释。我的直觉表明，应该有一种方法可以将架构放入架构中，但也许还有另一种我没有考虑过的解决方案。任何帮助或方向将不胜感激。提前致谢。

Answer 1

看起来你在向后做这件事。为此，我使用http://swagger.io上的编辑器创建了一个指定API的. yaml文件

这样你的。yaml文件可以为每种数据类型指定不同的DTO，您可以为每个API指定它返回什么类型。

此外，您不会发布响应DTO类的外观。我希望你已经把它生成了：

public class ResponseDTO<T> {
  public T getData() { … }
  …
}

但我不确定这样拥有自己的对象是不是个好主意。在我过去的一些项目中，我们为每种数据类型定义了一个单独的响应类，但是它们都做同样的事情！你的框架可能已经为你写了这样一个类。

你正在使用Spring靴，这就是我使用的。对于Spring，该类是组织Spring框架。（其他框架可能有自己的版本。而且它是通用的，因此您可以向其添加任何数据类型的内容。但 Swagger 要求您指定所添加内容的类型，而不是响应实体类本身。您的响应DTO类正在妨碍您。

因此，如果要返回一种类型的自定义产品，则 swagger 生成的批注将指定 CustomProduct.class，并且您的服务方法将如下所示：

… (more annotations)
@ApiResponses(value = { 
  @ApiResponse(code=200, message="Found", response=CustomProduct.class)
})
public ResonseEntity<CustomProduct> getCustomProduct(…) {
  CustomProduct myCustomProduct = retrieveCustomProduct(…);
  return new ResponseEntity<>(myCustomProduct, HTTPStatus.OK);
}

Answer 2

我成功地用@Schema标记了类的字段，它工作得很好，但是我用它来给出map的信息。

class CreateReq extends DTO {

    @Schema(description="",
        implementation = Products.class)
    Map<String,Map<String,Object>>  products;

}

    // For openapi document only
    private static class Products {
        ProductFields productId1;
        ProductFields productId2;
    }

    // For openapi document only
    private static class ProductFields {
        String field1;
        Object field2;

    }

Answer 3

我知道这个帖子是旧的，但我还是要发这个帖子，以防有人有类似的问题。

我还必须返回一个对象列表，其中这些对象的一个字段必须根据某些请求参数进行更改。为了在 Swagger 中记录这些子模式（如您所说，模式内部的模式），您可以使用@Schema注释的 oneOf 属性并提供泛型类的列表。

下面是一个示例：

< code>Customer.java:

java prettyprint-override">public class Customer {

  // Some other fields...

  @Schema(
      description = "List of generic contents inside Customer",
      oneOf = {Bar.class, Foo.class})
  private List<IContent> contents;

}

< code>IContent.java只是一些接口(或者它可以是泛型类的任何超类):

public interface IContent extends Serializable { }

假设< code>Foo.java和< code>Bar.java是两个通用类:

public class Bar implements IContent {

  @Schema(description = "Some dummy name field inside Bar")
  private String dummyName;

  @Schema(description = "Some dummy number field inside Bar")
  private Integer dummyNo;

}

public class Foo implements IContent {

  @Schema(description = "Some dummy ID field inside Foo")
  private Long contentID;

}

如果您有不同于记录一个通用对象列表的需求，请参见其他子模式属性类型的allOf和anyOf属性。