给定以下类：
public class Controller1 {
@PostMapping(path = "endpoint/path/post", consumes = MediaType.APPLICATION_JSON_VALUE)
@Override
public ResponseEntity<RandomObject> create(RandomObject randomObject) throws Exception {
...
}
}个字符
您会注意到，这两种方法之间的唯一区别（除了实现之外）是一种方法采用主体，而另一种方法不采用主体。
我的问题变成了如何在OpenAPI规范中定义这样的端点。
最后，我的目的是验证在控制器中定义的每个端点在相关的OpenAPI文件中都有定义。这通常很容易通过Map和请求类型的组合来完成。
然而，就我所知，定义这些方法的唯一方法是使用类似于以下的方法：
/endpoint/path/post:
post:
requestBody:
required: false型
我的问题基本上是这样的：
这是required属性的正确（预期）用法吗？或者它是为主体可空时设计的？
如果没有，是否有其他方法以明确的方式定义终点？
我在swagger documentation中找不到太多，除了下面这句话（相当不清楚）：
默认情况下，请求正文是可选的。要按要求标记几何体，请使用required：是的。
和this question使我认为，“optional”可能并不意味着是两种不同的方法，而是一个可为空的主体。
旁注：老实说，我甚至不知道spring-boot允许您定义具有相同Map+方法类型的方法，但显然这段代码已经在生产中，并且可以按预期工作。
2条答案
按热度按时间gfttwv5a1#
提供的代码将在Sping Boot 中正常工作。但是，根据OpenAPI规范，这是不允许的。因此，您不能为同一个路径/方法组合生成两个不同的规范。
OpenAPI将唯一操作定义为路径和HTTP方法的组合。这意味着不允许同一路径的两个GET或两个POST方法- * 即使它们具有不同的参数（参数对唯一性没有影响）*。
基于：https://swagger.io/docs/specification/paths-and-operations/
wtlkbnrh2#
你的一个端点（Controller1.create（））在请求体中期望一个RandomObject，而另一个端点（Controller2.createDifferent（））不期望任何人。要在OpenAPI规范中定义它，您应该使用required：对于第一个端点为true，并且是必需的：对于第二个，返回false（或者简单地忽略requestBody部分）。
OpenAPI规范的requestBody部分中的required属性指示请求是否需要请求主体本身，而不是主体中的单个属性是否可为空。如果设置为true，则API端点需要请求中的主体。如果为false，则可以在不使用body的情况下调用API端点。