带有 $ref to path 参数的 Swagger 2.0 语义错误

Question

我正在使用 Swagger Editor处理 JSON Swagger 2.0 API 定义。我已将我的定义简化为我遇到的问题的最小示例。当我使用引用对象来定义在多个端点之间共享的路径参数时会出现问题。

示例端点:
/my-api/{id}/some-thing
/my-api/{id}/some-other-thing

由于这些 id参数的定义方式相同，我将它们抽象为 parameters JSON 文件的一部分，并将它们包含在 "$ref": "#/parameters/testObjectId" 中.

Swagger 简化定义显示了这一点:

{
    "swagger": "2.0",
    "info": {
        "title": "Test Service",
        "description": "REST API for TestObjects",
        "version": "1.0.0"
    },
    "host": "api.not-a-real-url.com",
    "schemes": [
        "https"
    ],
    "basePath": "/api/test-objects",
    "produces": [
        "application/hal+json"
    ],
    "consumes": [
        "application/json"
    ],
    "paths": {
        "/{id}": {
            "get": {
                "operationId": "getTestObject",
                "summary": "Get a TestObject resource referenced by slug string ID",
                "security": [],
                "parameters": [
                    {
                        "$ref": "#/parameters/testObjectId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "schema": {
                            "type": "object",
                            "properties": {}
                        }
                    },
                    "default": {
                        "description": "Error",
                        "schema": {
                            "type": "object",
                            "properties": {}
                        }
                    }
                }
            }
        }
    },
    "parameters": {
        "testObjectId": {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "slug",
            "description": "Immutable, unique identifier of a TestObject"
        }
    },
    "definitions": {
    }
}

但是当这在 Swagger 中呈现时，我收到以下错误:

Errors

Semantic error at paths./{id}
Declared path parameter "id" needs to be defined as a path parameter at either the path or operation level

问题是 id实际上已定义，只是看起来抛出此错误的检查发生在 $ref 之前已经包括了。 Swagger 输出看起来正确。

此外，我已经使用这种方法大约 6 个月(只要我使用过 Swagger)，我现在才第一次遇到这个问题。有什么我应该做的不同的事情来防止这个错误吗？我这样做是不是在滥用 Swagger？

Answer 1

您的规范有效。它was a bug在 Swagger Editor v.3.2.2 中引入，在 v.3.2.3(2018 年 1 月 6 日发布)中修复。