带有 $ref 路径参数的 Swagger 2.0 语义错误

Question

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

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

由于这些 id 参数的定义方式相同，我将它们抽象到 JSON 文件的 parameters 部分，并将它们包含在 "$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 日发布）中修复。

带有 $ref 路径参数的 Swagger 2.0 语义错误

Swagger 2.0 semantic error with $ref to path parameter

swagger

swagger-2.0

swagger-editor

openapi