Bluemix : API Management - error "Swagger jsonReference". This is not supported. How do I fix it?

Question

I've tried to import swagger document in json format. I got the error

The field paths["/namespaces"].get.responses["401"] uses a Swagger jsonReference. This is not supported. Remove this field, or in-line the referenced JSON instead, and resubmit the request.

(I also attached the screenshot for just incase). The code snippet which might caused the error is like this:

"401": {
    "$ref": "#/responses/UnauthorizedRequest"
},
"500": {
    "$ref": "#/responses/ServerError"
}

What's wrong with this contents ? Appreciate if you could point me how to fix the problem.

Thanks !

Ref: screenshot

Answer 1

This error looks like a limitation/bug but as the error description suggests, you can in-line the definition to get around it. Here is an example of inlining references in a Swagger document.

The following Swagger document has a $ref

"responses": {
    "200": {
        "description": "Task retrieved",
        "schema": {
            "$ref": "#/definitions/Task"
        }
    },
    "404": {
        "description": "Task not found"
    }
}

...

"definitions": {
    "Task": {
        "type": "object",
        "required": [
            "deadline",
            "description",
            "status"
        ],
        "properties": {
            "description": {
                "type": "string",
                "example": "Make an app for Demo"
            },
            "status": {
                "type": "string",
                "example": "Created"
            },
            "deadline": {
                "type": "string",
                "format": "date",
                "example": "01/15/16"
            }
        }
    }

After inlining the $ref definition, the Swagger document would look like this:

"responses": {
    "200": {
        "description": "Task retrieved",
        "schema": {
          "type": "object",
          "required": [
              "deadline",
              "description",
              "status"
          ],
          "properties": {
              "description": {
                  "type": "string",
                  "example": "Make an app for Demo"
              },
              "status": {
                  "type": "string",
                  "example": "Created"
              },
              "deadline": {
                  "type": "string",
                  "format": "date",
                  "example": "01/15/16"
              }
          }
        }
    },
    "404": {
        "description": "Task not found"
    }
}