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

Posted 2021-04-07

我们使用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;
    }
}

发送/测试

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

将显示Dog.class

发送/测试

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

将显示Cat.class

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

答案

我和你一样有同样的问题。不幸的是，swagger-ui现在不支持。你可以在github上看到讨论。他们已就此开了几个问题。虽然昂首阔步仍然无法提供这一功能。它确实有一个解决方法，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