swagger-ui: $ref to external response schema not resolving

I have a Swagger 2.0 document which refers to external schema. Swagger UI is not fully resolving these external schema, even though they exist. There is no authentication on these resources.

It appears Swagger does not recognize “$ref” : “http://…” external schema. This is important to us, as we want to share schema across APIs, and reuse them from a central schema server.

I have swagger-ui runnning on port 80 in a Linux web server swagger.na.sas.com/swagger-ui (on our intranet). The server also has two contexts defined for /schema and for /apis:

When I view the swagger in Swagger UI,

http://swagger.na.sas.com/swagger-ui/?url=http://swagger.na.sas.com/apis/swagger.bugs/v1/swagger.json

the response schema are not resolved at all or not fully, even though I can view them all in the browser or via curl.

Example 1: operation “get” on “/c” using

                "400" : {
                    "description": "Success",
                     "schema" : { "$ref" : "http://swagger.na.sas.com/schema/swagger.bugs/error/v1/schema.json" }
                }

does not even show a model schema for 400 even though that schema resource exists. Using “/schema/swagger.bugs/error/v1/schema.json” has the same effect.

Example 2: operation “get” on “/a” has

                "400" : {
                    "description": "Success",
                    "schema" : { "$ref" : "#/definitions/error" }
                }

but Swagger UI shows empty model schema. definitions/error looks like

    "error" : {
        "schema" : { "$ref" : "http://swagger.na.sas.com/schema/swagger.bugs/error/v1/schema.json" }
    },

Example 3: operation “get” on “/b” with

                "400" : {
                    "description": "Success",
                    "schema" : { "$ref" : "#/definitions/errorResponse" }
                }

displays a model schema. “#/definitions/errorResponse” is embedded in the Swagger doc. However, that schema references an external property schema

            "links": {
                "type": "array",
                "description" : "An array of links to related resources and actions.",
                "items": { "$ref": "http://swagger.na.sas.com/schema/swagger.bugs/link/v1/schema.json" }
            },

which is not resolved; instead Swagger UI displays only “links” : [ null ]

A similar situation occurs when using an external $ref schema for a request body (parameter with “in” : “body” ) – nested properties defined by external schema do not resolve and are presented as null

https://drive.google.com/open?id=0B6GUPYh362KvUmRnYUxkNlVuZXM contains the sample swagger and schema files

apis/swagger.bugs/v1/swagger.json schema/swagger.bugs/a/v1/schema.json schema/swagger.bugs/error/v1/schema.json schema/swagger.bugs/link/v1/schema.json

About this issue

  • Original URL
  • State: closed
  • Created 9 years ago
  • Comments: 22 (10 by maintainers)

Most upvoted comments

And that’s why I asked you to join IRC because it’s much easier to cover in an interactive talk and not in comments.

In short: That’s not how JSON References work.

A bit more detailed: When you reference #/..../ the # means ‘this file’ (sort of). JSON References are parsed based on the file they exist it. It looks like you assume that the way JSON References is by pulling everything into the top-level file and then dereferencing - that’s not the case.

And for further details, please refer to https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/REUSE.md.