Validate with external files

[Ragnar-BY]

Problem statement

Swagger specification is splitted to some files, and files have refs to external files. When i try to validate it, I get errors about invalid reference

Swagger specification

2.0

Steps to reproduce

have files
swagger.yml

consumes:
  - application/json
produces:
  - application/json
schemes:
  - http
swagger: '2.0'
info:
  version: 1.0.0
  title: test
basePath: /test
paths:
  '/endpoint/{id}':
    parameters:
      - $ref: 'common.yml#/parameters/id'
    get:
      responses:
        '200':
          description: Fetched

and common.yml

parameters:
  id:
    type: string

run command go-swagger validate swagger.yml
got

The swagger spec at "swagger.yml" is invalid against swagger specification 2.0.
See errors below:
- some parameters definitions are broken in "/endpoint/{id}".GET. Cannot carry on full checks on parameters for operation 
- invalid reference: "common.yml#/parameters/id"
- path param "{id}" has no parameter definition

Environment

swagger version: dev (on moment 2019-08-15)
go version go1.12.7 linux/amd64
OS: ubuntu 16.10

[fredbi]

As for swagger 2.0 you can't put references arbitrarily like this.
Reusable parameters may be specified in a parameters section in the spec.
$ref is not a valid property in the definition of simple parameters (e.g. query, path).
$ref is valid for schemas or as references to the parameters or responses sections.

Finally, your parameter definition is invalid: it requires:

- name: id
  in: path
  required: true
  type: string

Here is the corrected example:

consumes:
  - application/json
produces:
  - application/json
schemes:
  - http
swagger: '2.0'
info:
  version: 1.0.0
  title: test
basePath: /test
parameters:
  id:
    name: id
    in: path
    required: true
    type: string
paths:
  '/endpoint/{id}':
    parameters:
      - $ref: '#/parameters/id'
    get:
      responses:
        '200':
          description: Fetched

[ansel1]

I don't understand the answer...it's true the parameters definition is missing sub-keys, but I'm not clear why the external reference doesn't work under a path item, but does work under an operation. According to the spec, both the Path Item object and the Operation object support a 'parameters' attribute, which can be either a Parameters Object or a Reference Object. And Reference Object is supposed to support external references.

To illustrate, I slightly modified the examples.

common.yml

parameters:
  id:
    name: id
    type: string
    in: path
    required: true

swagger.yml

consumes:
  - application/json
produces:
  - application/json
schemes:
  - http
swagger: '2.0'
info:
  version: 1.0.0
  title: test
basePath: /test
paths:
  '/endpoint/{id}':
    # if you uncomment this, you get an invalid reference error
#    parameters:
#      - $ref: 'common.yml#/parameters/id'
    get:
      # if you uncomment this instead, it works
#      parameters:
#        - $ref: 'common.yml#/parameters/id'
      responses:
        '200':
          description: Fetched

If you uncomment the first block, then run swagger validate swagger.yml, it fails. If you instead uncomment the second blocks, it works. Seems like a bug in the validator.

[casualjim]

According to the openapi specification 2.0 you can't have refs in parameters, only in the schema of a body parameter

If you go to look here: https://swagger.io/specification/v2/

You'll find there is no ref in those properties.
I think this works in openapi 3.0, but this project only deals with 2.0

[ansel1]

I must be misreading that document...I'm looking at the v2 docs. I look at the top level Swagger Object. That has a "paths" field of type Paths Object. Paths Object as a field "/{path}" of type Path Item Object. Path Item Object has a field "parameters", which is an array of either Parameter Object, or Reference Object. The definition of Reference Object indicates that it can accept local or external references. The definition of the "parameters" field on the Path Item object is identical to the definition on the Operation object. But they don't seem to work the same.

<root>: Swagger Object
  paths: Path Object
    /{path}: Path Item Object
      parameters: [Parameter Object | Reference Object]
      get: Operations Object
        parameters: [Parameter Object | Reference Object]

Also, if I copy the contents of common.yml into swagger.yml, and change the path parameters ref to an internal ref, it works. So it doesn't seem like the problem is related to using refs in path parameters, it seems to be about using an external ref.

consumes:
  - application/json
produces:
  - application/json
schemes:
  - http
swagger: '2.0'
info:
  version: 1.0.0
  title: test
basePath: /test
paths:
  '/endpoint/{id}':
    parameters:
      # an internal ref will work
      - $ref: '#/parameters/id'
      # but not an external one
#      - $ref: 'common.yml#/parameters/id'
    get:
      responses:
        '200':
          description: Fetched
parameters:
  id:
    name: id
    type: string
    in: path
    required: true