Path params defined in path objects with shared method $ref files behaving oddly in Swagger UI

[Austin]

I am working to document an API in Swagger 2.0 with multiple paths that share identical query string parameters and return schema format for their get methods:

        "/customers/invoices/{invoice}": {

            "parameters": [

                {

                    "name": "invoice",

                    "in": "path",

                    "description": "The Invoice id.",

                    "required": true,

                    "type": "string"

                }

            ],

            "get": {

                "$ref": "resources/invoices/get.json"

            }

        },

        "/customers/{customer}/invoices": {

            "parameters": [

                {

                    "name": "customer",

                    "in": "path",

                    "description": "The customer id.",

                    "required": true,

                    "type": "string"

                }

            ],

            "get": {

                "$ref": "resources/invoices/get.json"

            }

        },

        "/customers/{customer}/invoices/{invoice}": {

            "parameters": [

                {

                    "name": "customer",

                    "in": "path",

                    "description": "The customer id.",

                    "required": true,

                    "type": "string"

                },

                {

                    "name": "invoice",

                    "in": "path",

                    "description": "The Invoice id.",

                    "required": true,

                    "type": "string"

                }

            ],

            "get": {

                "$ref": "resources/invoices/get.json"

            }

        }

Now when I view this in Swagger UI v3.0.19 the path parameters that are defined up in the path objects are somehow being shared across all three paths as being required. I would expect that the first two should only show their single path parameter.  I have tried changing all the path parameters in each one to be something unique from the others and yet they still get lumped together. Aside from this the $ref doesn't appear to cause any other issue as all three do show the additional shared querystring parameters and the shared schema just fine. I've also tried removing the shared query string parameters from the shared $ref file to see if somehow that was causing them to share all parameters and it didn't stop the problem.

I'm a bit confused on whether what I am doing is technically allowable or not because in the guidelines for reuse it states that Operations can be referenced (https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/REUSE.md#operations), but the example shown appears to be a path object that is being referenced and not the operation object (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#path-item-object). 

Am I missing something here or is this just an issue in the latest version of Swagger UI maybe?

[Ron Ratovsky]

Hi Austin,

 

It’s kinda hard to test because your definition is indeed not valid.

You can reference paths, not operations.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Austin]

Thanks for the reply, though that sounds to me like the documented guidelines for reuse are wrong. The example under operations does seem to agree however. I'll try refactoring the way I'm breaking up the swagger document and reply back on here with what I find. 

What is reusable

The following types are reusable, as defined by the spec:

• Parameters
• Models (or Schema Objects in general)
• Responses
• Operations (Operations can only be remote references)

source: https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/REUSE.md#what-is-reusable

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Ron Ratovsky]

Yeah, I agree. The wording in the guidelines is confusing. You can reuse operations under a path, not individual operations.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Austin]

Thanks, I appreciate the help in understanding how it is supposed to work. Though I do have to say that the current implementation is a bit disappointing as I can't think of when it would be useful to reference the entire contents of a path object considering different paths will likely have different path parameters.