Swagger-editor: 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: [email protected]
    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:

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: [email protected]
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 [e-mail] 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 ) :