Question

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

示例端点：
/我的API / {ID} /一些，事情
/我的-API / {ID} /一些-另一事

由于这些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

您的规格有效。它在Swagger Editor v.3.2.2中引入was a bug，它在v.3.2.3（2018年1月6日发布）中得到修复。

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

1 个答案: