Swagger 2.0 semantic error with $ref to path parameter

Question

I am using Swagger Editor to work on a JSON Swagger 2.0 API definition. I have reduced my definition to a minimum example of the problem I am experiencing. The problem occurs when I use a reference object to define a path parameter that is shared between multiple endpoints.

Example endpoints:
/my-api/{id}/some-thing
/my-api/{id}/some-other-thing

Since these id parameters are defined the same way, I abstracted them to the parameters section of the JSON file, and included them with "$ref": "#/parameters/testObjectId".

The Swagger reduced definition shows this:

{
    "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": {
    }
}

But when this is rendered in Swagger, I get the following error:

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

The problem is that id is actually defined, only it appears that the check which throws this error is occurring before the $ref is included. The Swagger output looks correct.

Further, I have used this approach for about 6 months (as long as I have used Swagger) and I am just now running into the problem for the first time. Is there something I should be doing differently to prevent this error? Am I misusing Swagger by doing it this way?

Answer 1

Your spec is valid. It was a bug introduced in Swagger Editor v.3.2.2, it was fixed in v.3.2.3 (released on January 6, 2018).