APIDevTools / swagger-cli

Swagger 2.0 and OpenAPI 3.0 command-line tool
https://apitools.dev/swagger-cli
MIT License
516 stars 68 forks source link

External references are not all resolved before local references #17

Closed fgimian closed 6 years ago

fgimian commented 6 years ago

Hi guys, thanks for your great work on this project.

I noticed that a scenario such as the one shown here fails as this CLI seems to resolve references top to bottom rather than resolving external file references first and then local references second.

fots ~ > test $ tree
.
├── definitions
│   ├── User.yaml
│   └── index.yaml
├── index.yaml
├── info
│   └── index.yaml
└── paths
    ├── bar.yaml
    ├── foo.yaml
    └── index.yaml

3 directories, 7 files
fots ~ > test $ swagger-cli validate index.yaml 
Error resolving $ref pointer "/Users/fots/test/paths/bar.yaml#/definitions/User". 
Token "definitions" does not exist.

The reason this happens is that once the CLI reaches the bar path, it sees:

get:
  responses:
    200:
      description: OK
      schema:
        $ref: '#/definitions/User'

And it attempts to resolve local ref #/definitions/User' prior to referencing the external definition files.

Any help would be greatly appreciated 😄 Fotis

JamesMessinger commented 6 years ago

In the example that you gave above, #/definitions/User does not exist, which is why it causes an error. If you meant to reference your definitions/User.yaml file, then you use a file reference, rather an a JSON Pointer. Like this...

get:
  responses:
    200:
      description: OK
      schema:
        $ref: 'definitions/User.yaml'

Or, if you prefer to keep all of your definitions in the "definitions" section of your schema, then you can do something like this...

get:
  responses:
    200:
      description: OK
      schema:
        $ref: '#/definitions/User'
definitions:
  User:
    $ref: 'definitions/User.yaml'