How can we improve Azure API Management?

Support Swagger Documentation - Object representation with nested $ref issue

Hi,

There is an issue regarding Swagger file for complex objects which are using nested $ref, according to the program team, it's not supported yet by API Management although it works well in Swagger UI.

This is for me a big issue as we can't manage documentation manually in case our object definition evolve. Furthermore, even if we put manually a json object example in APIM Publisher portal, we can't define the object model associated to it.

Could you please make Swagger documentation work with nested $ref in APIM?

Thanks.

87 votes
Vote
Sign in
(thinking…)
Sign in with: oidc
Signed in as (Sign out)
You have left! (?) (thinking…)
Michal Holubek shared this idea  ·   ·  Flag idea as inappropriate…  ·  Admin →

6 comments

Sign in
(thinking…)
Sign in with: oidc
Signed in as (Sign out)
Submitting...
  • Laszlo commented  ·   ·  Flag as inappropriate

    Hi,
    Any news on this item?
    Tried the link from trello, but was not valid.
    Thanks,
    Laszlo

  • Francois LASNE commented  ·   ·  Flag as inappropriate

    second level of correction support recursive reference , here is a use case ,
    recursion is here to provide the call stack pattern ,

    here you have an error with a field cause that is as well an error

    this use case is supported into swagger.io ( there was some bug in the past ) but is not ok in APIM

    "Error": {
    "type": "object",
    "description": "The RFC 7807 defined Problem Details for HTTP APIs , is as of today proposed standard, and it SHOULD be applied. It proposes a seamless structure for common pattern of errors as same as an extension mechanism",
    "required": [
    "title"
    ],
    "properties": {
    "type": {
    "type": "string",
    "description": "A URI reference [RFC3986] that identifies the problem type"
    },
    "title": {
    "type": "string",
    "description": "A short human-readable summary of the problem type"
    },
    "status": {
    "type": "string",
    "description": "The HTTP status code generated by the origin server for this occurrence of the problem"
    },
    "details": {
    "type": "string",
    "description": "A human-readable explanation specific to this occurrence of the problem"
    },
    "instance": {
    "type": "string",
    "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced"
    },
    "cause": {
    "$ref": "#/definitions/Error"
    }
    }
    }

  • Derk H commented  ·   ·  Flag as inappropriate

    Agree, this is blocking the setup of our developer portal with our API's that contain nested #ref's.

  • Duane Tharp commented  ·   ·  Flag as inappropriate

    Disclosure - I work for Stoplight - Stoplight provides an OAS/Swagger modeling solution that fully supports nested $refs and complex JSON Schema objects. You can then export the specification from Stoplight and have the $refs all resolved for import into API Management.

  • wenxin shi commented  ·   ·  Flag as inappropriate

    I have same issue here, seems the APIM can only solve 2 levels of nestd $ref, if the model have deeper nested levels, it will fail. following is an example.

    {"swagger":"2.0","info":{"version":"v1","title":"testapi"},"host":"tset.com","schemes":["http"],"paths":{"/api/v1/rawevent":{"post":{"tags":["RawEvent"],"operationId":"RawEvent_Post","consumes":["application/json","text/json","application/xml","text/xml","application/x-www-form-urlencoded"],"produces":["application/json","text/json","application/xml","text/xml"],"parameters":[{"name":"rawEvent","in":"body","required":true,"schema":{"$ref":"#/definitions/SimulateRawEvent"}}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/SimulateRawEvent"}}},"400":{"description":"BadRequest"},"401":{"description":"Unauthorized"}}}},"/api/v1/eventtypes":{"get":{"tags":["RawEvent"],"operationId":"EventTypes_Get","consumes":[],"produces":["application/json","text/json","application/xml","text/xml"],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/EventType"}}},"400":{"description":"BadRequest"},"401":{"description":"Unauthorized"}}}},"/api/v1/vehicles/events":{"get":{"tags":["Vehicles"],"operationId":"VehicleEvents_Get","consumes":[],"produces":["application/json","text/json","application/xml","text/xml"],"parameters":[{"name":"minReceived","in":"query","required":true,"type":"string","format":"date-time"}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/VehicleEvent"}}},"400":{"description":"BadRequest"},"401":{"description":"Unauthorized"}}}},"/api/v1/vehicles/faults":{"get":{"tags":["Vehicles"],"operationId":"VehicleFaults_Get","consumes":[],"produces":["application/json","text/json","application/xml","text/xml"],"parameters":[{"name":"minReceived","in":"query","required":true,"type":"string","format":"date-time"}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/VehicleFault"}}},"400":{"description":"BadRequest"},"401":{"description":"Unauthorized"}}}},"/api/v1/vehicles/trips":{"get":{"tags":["Vehicles"],"operationId":"VehicleTrips_Get","consumes":[],"produces":["application/json","text/json","application/xml","text/xml"],"parameters":[{"name":"minReceived","in":"query","required":true,"type":"string","format":"date-time"}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/VehicleTrip"}}},"400":{"description":"BadRequest"},"401":{"description":"Unauthorized"}}}}},"definitions":{"SimulateRawEvent":{"type":"object","properties":{"Serial":{"format":"int64","type":"integer"},"Lat":{"format":"double","type":"number"},"Long":{"format":"double","type":"number"},"SpeedMps":{"format":"float","type":"number"},"Direction":{"format":"int32","type":"integer"},"EventTypeId":{"format":"int32","type":"integer"},"Observed":{"format":"date-time","type":"string"}}},"EventType":{"type":"object","properties":{"Id":{"format":"int32","type":"integer"},"Name":{"type":"string"}}},"VehicleEvent":{"type":"object","properties":{"Serial":{"format":"int64","type":"integer"},"Received":{"format":"date-time","type":"string"},"Observed":{"format":"date-time","type":"string"},"EventTypeId":{"format":"int32","type":"integer"},"Speed":{"format":"double","type":"number"},"SpeedLimit":{"format":"double","type":"number"},"Location":{"$ref":"#/definitions/Location"},"Address":{"$ref":"#/definitions/Address"},"Direction":{"format":"int32","type":"integer"}}},"Location":{"type":"object","properties":{"Latitude":{"format":"double","type":"number"},"Longitude":{"format":"double","type":"number"}}},"Address":{"type":"object","properties":{"Street":{"type":"string"},"Town":{"type":"string"},"Postcode":{"type":"string"}}},"VehicleFault":{"type":"object","properties":{"Serial":{"format":"int64","type":"integer"},"Received":{"format":"date-time","type":"string"},"Observed":{"format":"date-time","type":"string"},"FaultCode":{"type":"string"},"IsEngineLightOn":{"type":"boolean"}}},"VehicleTrip":{"type":"object","properties":{"Serial":{"format":"int64","type":"integer"},"Received":{"format":"date-time","type":"string"},"StartPoint":{"$ref":"#/definitions/TripPoint"},"EndPoint":{"$ref":"#/definitions/TripPoint"},"Distance":{"format":"double","type":"number"}}},"TripPoint":{"type":"object","properties":{"Observed":{"format":"date-time","type":"string"},"Address":{"$ref":"#/definitions/Address"},"Location":{"$ref":"#/definitions/Location"}}}}}

Feedback and Knowledge Base