java - 如何在 Swagger 中描述多态端点？

Question

我们使用Spring+Jackson(Java)。在我们的 API 中，我们可以将不同的对象发送到同一个端点。 例如

@JsonTypeInfo(
    use = JsonTypeInfo.Id.NAME, 
    include = As.PROPERTY, 
    property = "type")
@JsonSubTypes({
    @JsonSubTypes.Type(value = Dog.class, name = "dog"),
    @JsonSubTypes.Type(value = Cat.class, name = "cat")
})
public static class Animal {
}

@JsonTypeName("dog")
public static class Dog extends Animal {
    public double barkVolume;
}

@JsonTypeName("cat")
public static class Cat extends Animal {
    boolean likesCream;
    public int lives;
}

@Controller
public class MyController {

    //REST service
    @RequestMapping( value = "test")
    public  @ResponseBody String save(@RequestBody  Animal animal){
        System.out.println(animal.getClass());
        return success;
    }
}

发送到/test

{
    "type": "dog",
    "barkVolume": 23.3
}

将显示 Dog.class

发送到/test

{
    "type": "cat",
    "likesCream": true,
    "lives": 42
}

将显示 Cat.class

如何在 Swagger 中描述多态端点？

Answer 1

我遇到了和你一样的问题。不幸的是，swagger-ui 现在不支持它。 你可以在github上看到讨论。他们已经就此提出了几个问题。而 swagger 仍然无法提供该功能。确实有解决方法，github上有人提到过，也许你可以试试。

ringgelerch commented on Aug 10

This is a very important feature for us as well. We use a workaround at the moment:

For the GET method we define multiple responses like "200 Cat" and "200 Dog". For PUT and POST we use different paths like "path/to/animals/animal (Cat)". To use the "try out" feature of swagger ui we created a PUT and POST with the valid path "path/to/animals/animal". To send a request just copy the body content from the Cat PUT or POST to the generic one.

It would be greate to see the discriminator be supported very soon, because with upper workaround our api spec is hard to maintain and the rendered ui is not easy to read.

链接在这里
https://github.com/swagger-api/swagger-ui/issues/2438 或 https://github.com/swagger-api/swagger-ui/issues/1526