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

【问题标题】：How to describe polymorphic endpoint in Swagger?如何在 Swagger 中描述多态端点？
【发布时间】：2017-07-31 15:44:47
【问题描述】：

我们使用 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 中描述多态端点？

【问题讨论】：

标签： java spring jackson polymorphism swagger

【解决方案1】：

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

ringgelerch 于 8 月 10 日发表评论

这对我们来说也是一个非常重要的功能。我们目前使用一种解决方法：

对于 GET 方法，我们定义了多个响应，例如“200 Cat”和“200 Dog”。对于 PUT 和 POST，我们使用不同的路径，例如“path/to/animals/animal (Cat)”。为了使用 swagger ui 的“试用”功能，我们使用有效路径“path/to/animals/animal”创建了一个 PUT 和 POST。要发送请求，只需将正文内容从 Cat PUT 或 POST 复制到通用的。

很高兴看到鉴别器很快得到支持，因为有了上面的解决方法，我们的 api 规范很难维护，渲染的 ui 也不容易阅读。

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

【讨论】：