json - 在 Swagger-UI 中覆盖动词级模型/模型架构

Question

我正在使用 swagger-ui 尝试标准化 API 文档。我意识到，对于使用 body 参数并因此需要显示模型和模型架构的动词(GET、PUT、POST 等)，架构是在资源级别(宠物商店中的/pet 或/store)定义的例子)。但是，在我们的 API 中，所需的主体参数将从动词更改为动词，最好为每个参数都有一个模型来准确反射(reflect)这一点。
http://petstore.swagger.wordnik.com/api/api-docs/pet 中模型定义的当前版本，其中模型定义是这样的:


有没有办法在动词级别覆盖默认的资源级别模型？

Answer 1

在 swagger 2.0 规范中，每个资源都有用于 HTTP 方法(get、post、delete 等)的子部分。每一个都有一个参数标签，它映射到下面形式的 JSON 对象列表。为了使该主体使用单独的模式，可以使用模式标记和 $ref 覆盖它。子标签，然后引用您在底部定义小节中单独提供的定义。

{
    name: "body",
    in: "body",
    description: "set the properties of a pet",
    schema: {
        $ref: "#/definitions/PetPut"
    },
    required: true
}