Start a new topic
Solved

References for top level swagger properties showing errors

Howdy


Im trying to do a centralized security and securityDefinitions sections for our APIs.


With the API definitions like this. 

swagger: '2.0'
info:
  version: '2.0.0'
  title:  Some API
  description: Provides an interface for something
basePath: /usage/2
consumes:
  - application/json
produces:
  - application/json
securityDefinitions: 
  $ref: '../../../shared/commons/2/security.yaml#/securityDefinitions'
security:
  $ref: '../../../shared/commons/2/security.yaml#/security'

  And the referenced file like this

 

swagger: '2.0'
info:
  version: '2'
  title: Common Security Objects
paths: {}
securityDefinitions:
  api_key_query_token:
    description: "blah blah blah in query string`\n"
    type: "apiKey"
    name: "api-key"
    in: "query"
  api_key_header:
    description: "blah blah blah in header"
    type: "apiKey"
    name: "X-Api-Key"
    in: "header"
  
security:
  - api_key_query_token: []
  - api_key_header: []
  

 

The normailization of this works via the SwaggerNormalizerGenTemplate, but in the UI it shows errors on the API model in all the Viewers. 


I get two different errors showing on these references in the API spec.


image


and 


image


Is there any way around this   or could this sort of references be supported by the UI?  As I understand it these are valid YAML reference types.  


Thanks

-=Brian

1 Comment

Hi Brian, 


The Swagger-OpenAPI 2.0 specification only allows JSON references in specific places:

  • Path Items
  • Schema Definitions
  • Parameters
  • Responses

You've used the correct reference syntax, it's just not supported in this context. 

As you've discovered, Swagger-Normalizer tries to resolve JSON references wherever you put them. So if you'd like to see an option in API Studio to tolerate references out of the allowed contexts, I think this would be a great suggestion for the RepreZen feature requests forum.  

(For example, this could take the form of a "severity" for unsupported references, with Error, Warning and Ignore options.)


Ted Epstein |   |      skype:ted.epstein


Login or Signup to post a comment