Enable entry of multiple examples for a given operation
The portal only permits one example of a 200 OK response. I worked around this limitation by creating a larger JSON object consisting of an array of examples one property of which is the actual response.
E.g.,
[
{
"Example": 1,
"Description": "No filters are applied. Consequently, there are more than 25 results",
"RequestUrl": "<a rel="nofollow noreferrer" href="https://apis.conmetwheelends.com/aftermarket/v2/details/summary/~/~"">https://apis.conmetwheelends.com/aftermarket/v2/details/summary/~/~"</a>,
"Response": {
"Status": "TOO_MANY_RESULTS",
"Message": "Indicates that the request was successful (it was a valid). However, the response returned too many results. This may occur if the request is under-constrained based on current data. Please apply additional filters to further constrain the result set."
}
},
{
"Example": 2,
"Description": "Invalid part number: 104103 is not an OEM hub assembly number (it's a hub machining number).",
"RequestUrl": "<a rel="nofollow noreferrer" href="https://apis.conmetwheelends.com/aftermarket/v2/details/summary/~/104103"">https://apis.conmetwheelends.com/aftermarket/v2/details/summary/~/104103"</a>,
"Response": {
"Status": "ZERO_RESULTS",
"Message": "Indicates that the request was successful (it was a valid) but nevertheless returned no results. This may occur if the request is over-constrained based on current data."
}
},
{
"Example": 3,
"Description": "Fetch detail summaries for all associated aftermarket parts (i.e., all part types) for valid OEM hub assembly number 10031065",
"RequestUrl": "<a rel="nofollow noreferrer" href="https://apis.conmetwheelends.com/aftermarket/v2/details/summary/~/10031065"">https://apis.conmetwheelends.com/aftermarket/v2/details/summary/~/10031065"</a>,
"Response": {
"Status": "OK",
"Results": [
{
"OemHubassemblyNumber": "10031065",
"AftermarketPartDetailSummaries": [
{
"AftermarketPartNumber": "10082207",
"Description": "ASSY PRESET AFMKT PREMIUM FF FR HP10 ABS",
"AftermarketPartType": "Complete Hub Assembly",
"HubCastingMaterialType": "Aluminum",
"HubAssemblyType": "PreSet Hub Assembly (Aftermarket)"
},
{
"AftermarketPartNumber": "10045872",
"Description": "HUB SERVICE KIT-PreSet FF Flat Nut Brg",
"AftermarketPartType": "PreSet Hub Assembly Complete Rebuild Kit (D Flat)"
},
{
"AftermarketPartNumber": "10045871",
"Description": "HUB SERVICE KIT-PreSet FF Key Nut Brg",
"AftermarketPartType": "PreSet Hub Assembly Complete Rebuild Kit (Keyway)"
},
{
"AftermarketPartNumber": "10081727",
"Description": "HUB SERVICE KIT - FF FRONT",
"AftermarketPartType": "PreSet/PresSet+ Rebuild Kit"
}
]
}
]
}
},
{
"Example": 4,
"Description": "Fetch detail summaries for all associated aftermarket hub assemblies (aftermarketPartTypeId=1) for two valid OEM hub assembly numbers: 10031065 & 10001119",
"RequestUrl": "<a rel="nofollow noreferrer" href="https://apis.conmetwheelends.com/aftermarket/v2/details/summary/1/10031065,10001119"">https://apis.conmetwheelends.com/aftermarket/v2/details/summary/1/10031065,10001119"</a>,
"Response": {
"Status": "OK",
"Results": [
{
"OemHubassemblyNumber": "10001119",
"AftermarketPartDetailSummaries": [
{
"AftermarketPartNumber": "10082203",
"Description": "ASSY PRESET AFMKT PREMIUM FF FR HP10 ABS",
"AftermarketPartType": "Complete Hub Assembly",
"HubCastingMaterialType": "Aluminum",
"HubAssemblyType": "PreSet Hub Assembly (Aftermarket)"
}
]
},
{
"OemHubassemblyNumber": "10031065",
"AftermarketPartDetailSummaries": [
{
"AftermarketPartNumber": "10082207",
"Description": "ASSY PRESET AFMKT PREMIUM FF FR HP10 ABS",
"AftermarketPartType": "Complete Hub Assembly",
"HubCastingMaterialType": "Aluminum",
"HubAssemblyType": "PreSet Hub Assembly (Aftermarket)"
}
]
}
]
}
}
]
19
votes
Calvin Craig
shared this idea
1 comment
-
Christi Schneider
commented
I'd like to add some more context to this because I think it is important.
OpenApi 3 allows for `examples` to be provided in addition to `example`.
This is specifically called out in the APIM documentation as not supported - https://docs.microsoft.com/en-us/azure/api-management/api-management-api-import-restrictions#-openapi-version-3
The way APIM behaves is it will completely ignore `examples` if it is provided, not emitting it in the OpenApi document that can be downloaded in the developer portal and not displaying any example in the UI. At minimum, if `examples` is provided but `example` is not, one of the values in `examples` should be included as the `example` surfaced in APIM instead of leaving it blank.
I've attached a screenshot of how examples are displayed in Swagger UI.
