对一个端点下的多个谓词的OpenAPI引用

Question

在编写代码之前，我将采用创建您的API文档的方法，而且我对OpenAPI规范还很陌生。

这是我的openapi.yaml文件的一部分：

paths:
/player/{playerId}:
get:
$ref: paths/player/get.yaml
put:
$ref: paths/player/put.yaml
patch:
$ref: paths/player/patch.yaml

这对我来说完全有道理，但出于某种原因，它没有得到支持？我想把我的动词分别归档。有人有什么建议吗？为你的帮助干杯！

Answer 1

我认为这是不可能的。仅当规范明确提到支持$ref时，才支持$ref。

在您的情况下，https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#operationObject是有趣的对象。它没有列出$ref，因此，不幸的是，它不受支持。

您可以在路径级别执行$ref(https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#pathItemObject)：

这看起来像这样：

paths:
/player/{playerId}:
$ref: paths/player/playerId.yaml

playerId.yaml是这样的：

get:
# content of paths/player/get.yaml
put:
# content of paths/player/put.yaml

patch:
# content of paths/player/patch.yaml