here's the problem I encountered when I try to add a Front End Swagger document into our team API.
In my original Swagger document (Swagger 2.0), I have a field under the path mentioned response body:
responses:
'200':
description: Success
schema:
$ref: '#/definitions/QueryResponse'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
However once I saved the documents inside the API Management Front End using the OpenAPI Editor, I found the $ref inside the responses are all gone, the document automatically changed to these:
responses:
'200':
description: Success
'401':
description: Unauthorized (ensure correct authorization header in the request)
'403':
description: >-
Forbidden to perform the operation (ensure the client has correct
role for the partition Id)
Not only the $ref for 401 and 403 becomes directly taken text from the responses object, but the schema inside the 200 response is also missing. In my responses under root level it is written like:
responses:
'401':
description: Unauthorized (ensure correct authorization header in the request)
'403':
description: Forbidden to perform the operation (ensure the client has correct role for the partition Id)
This responses field also missing from the document once I saved.
And in my definitions under root level, there is the QueryResponse schema:
QueryResponse:
properties:
timestamp:
example: '2019-08-09T10:04:50.49476Z'
type: string
message:
example: 'Hello'
type: string
type: object
This schema remained in the document after saved, but because of the $ref is missing from 'responses' field under the 'path', so it did not show as well.
While I also try to input the OpenAPI 3.0 document, I rewrite the document following the official documentation, I also checked about support for OpenAPI 3.0 in API Management, apparently, it is supported under Preview Feature. However, when I input the whole 3.0 document into the editor and was about to save, it shows an error called:
One or more fields contain incorrect values:
Parsing error(s): The Swagger version specified is unknown.
I have checked that in OpenAPI 3.0 there is no 'swagger' field anymore, instead, it is replaced by 'openapi' field, which I put right on the top of the document: openapi: 3.0.0
May I know what is the problem for the missing $ref in 2.0 or the error in 3.0? Thanks and really appreciates if any helps.
UPDATES
The missing schema is solved by putting below field into responses:
produces:
- application/json
However, now it makes the other responses such as 400, 401 and 403 have the column 'Representations' which shows an empty column row. I do not want that, is there any other way to only apply the produces to the response 200 only? Because that is the only response that haves a JSON body.
Also, the $ref of 401 and 403 still missing and description is taken from the 'responses' under root level.
