using $ref under a path fails for parameters

[jmelching]

• OS: macOS
• Browser: chrome
• Version: 72.0.3626.121
• Method of installation: latest docker and https://editor.swagger.io/?url=http://localhost:8080/test.yaml
• Swagger-Editor version: latest
• Swagger/OpenAPI version: OpenAPI 3.0

Content & configuration

Example Swagger/OpenAPI definition:

openapi: 3.0.0
info:
  title: Test
  description: Test YAML
  version: '1.0'
  contact:
    name: API Support
    email: test@test.com
    url: http://test.com/support
tags:
  - name: test
    description: test
servers:
  - url: http://localhost
paths:
  /employees/{id}:
    $ref: "paths/employees.yaml#/getEmployeeById"
components:
  schemas:
    employee:
      type: object
      properties:
        name:
          type: string
      required:
        - name
  parameters:
    id:
      name: id
      description: test
      in: path
      required: true
      schema:
        type: string

paths/employees.yaml

getEmployeeById:
  get:
    operationId: getEmployeeById
    description: test
    tags:
     - test
    parameters:
      - $ref: '../test.yaml#/components/parameters/id'
    responses:
      200:
        description: Success
        content:
          application/json:
            schema:
              $ref: '../test.yaml#/components/schemas/employee'

Describe the bug you're encountering

When using $ref under paths: above the editor gives

Semantic error at paths./employees/{id}
Declared path parameter "id" needs to be defined as a path parameter at either the path or operation level
Jump to line 16

If I remove the $ref and include the contents of employees.yaml directly, the validation passes. I also used wework/speccy to validate the yaml and it passes when using $ref.

± |master {5} S:2 U:3 ?:1 ✗| → docker run -v $PWD/openapi:/project wework/speccy lint test.yaml
Specification is valid, with 0 lint errors

To reproduce...

Steps to reproduce the behavior:

1. Create test.yaml as above.
2. Create paths/employees.yaml as above.
3. Navigate to https://editor.swagger.io/?url=http://localhost:8080/test.yaml
4. Validation error will appear at top.

Expected behavior

Should be valid according to the openapi 3.0 spec

[peteclay]

I have the exact same issue. The parameter still renders in swagger-ui and passes validation but throws the semantic error.

Steps to reproduce the behavior: Serving up OpenApi 3.0.0 spec with multiple files using node http-server locally.

Defining the in path parameter in line works fine.

[mariotoffia]

I've got the (about the) same issue #1976 - I just didn't see this before sumitting my issue. I've got a reference that has a reference and the latter is not resolved and therefore an error occurs. If I do define components/parameters/xyz: directly it will work...

Cheers, Mario

[mariotoffia]

Also same goes for reference in info of which gives:

Errors
Hide

Structural error at info
should NOT have additional properties
additionalProperty: $ref
Jump to line 3
Structural error at info
should have required property 'title'
missingProperty: title
Jump to line 3
Structural error at info
should have required property 'version'
missingProperty: version
Jump to line 3

the main file:

openapi: 3.0.1

info:
  $ref: 'device-local-api/info.yaml'
externalDocs:

and the info.yaml

version: 1.0.0.SNAPSHOT
title: Test title
description: Test
termsOfService: 'http://foobar.io'
contact:
  email: apiteam@foobar.io
license:
  name: Apache 2.0
  url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

Works well using my visual studio code plugin but fails with errors above using swagger editor.

Cheers, Mario

[shockey]

@mariotoffia that error is valid - as the spec indicates, OpenAPI Object info values can only be Info Objects. $refs are only allowed where Reference Object is mentioned.

[mariotoffia]

@shockey Thanks for that info! :)

[peteclay]

Yes, but $refs for URL parameters should work, correct? (noting that they do "work" in the swagger-ui but throw that error I screen-shot in the swagger-editor)

On Fri, Apr 12, 2019 at 5:26 AM kyle notifications@github.com wrote:

@mariotoffia https://github.com/mariotoffia that error is valid - as the spec indicates, OpenAPI Object https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#openapi-object info values can only be Info Objects https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#infoObject. $refs are only allowed where Reference Object https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#referenceObject is mentioned.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/swagger-api/swagger-editor/issues/1972#issuecomment-482272325, or mute the thread https://github.com/notifications/unsubscribe-auth/AEPcdy6a3ovsrGi3Im-vJko9MgjFZdcXks5vf4xlgaJpZM4cSot4 .

[shockey]

@peteclay yeah, the case you shared a screenshot of is valid - it's Swagger Editor wrongly not considering the content of the remote reference for validation here!

[jy95]

I encountered the same $ref issue with my specification

Other tools don't have this issue (for example redoc and openapi-generator ) :

[orinoco]

Still an issue. It's just an (incorrect) validation error. Beyond clogging up the preview with a bunch of errors that don't actually exist, it's just an inconvenience. Does make it hard to spot real errors though.

Just for reference, the preview still works. no errors in other openapi editors, and it passes validation.

npx @openapitools/openapi-generator-cli validate -i openapi.yaml
No validation issues detected.