To complete the swagger documentation we need publish various custom html response codes.
like this:
Can you please elaborate on how this important for you? Usually those Swagger responses are mostly innocuous.
I don't think that these values are "innocuous". This belongs to a complete documentation! We make heavy use of this information to build a robust application
Ok, I suggest someone open a feature request so we can better discuss how you expect such information to be provided to XData.
I will look for it. Without knowing the reponse code you need the source code to find someting like this here. I had few weeks ago such an API. Due the missing knowing of possible response codse the API did work work very well.
HTTP status code are standard and it should be wise that any client making requests to a REST server handle the known status codes like 4xx and 5xx, regardless they are present in the Swagger document.
Thats right, but some API will use custom codes and if you try to handle all 200 possible 4xx and 5xx codes this would blow up each API call enourmous ;-)
Hoewever, this should document the codes a foreign develeper may not expect and have to implement. I know a lot peoples think: Real developers need no documentation. Although swagger/open-API has been born. 
1 Like
Yes, no problem. Please open the feature request so we can better discuss how this could be provided to the OpenAPI spec from the code.
An example of what I mean can be found here:
https://staging.convercus.io/api-docs/swagger-ui.html?urls.primaryName=account#
See in section /accounts/{accountId}/bookings
I understand. Well, as I said, those listed status codes add no semantic meaning to what already is known about those status codes. But I understand that you want to trust the Swagger specs that no other status codes are answered by that endpoint besides those that are listed (something I see not always happen).
As I said, we can implement that eventually, please file a feature request for that so in future developers can explicitly mention what are the status code a XData endpoint returns.
Just for you to have an idea of what I'm talking about, if you take Pet Store Swagger example, which should be the "definitive" example of using Swagger: Swagger UI
In UpdatePet endpoint you have these responses listed:
So, does it really mean those responses are the only ones provided by the endpoint? Of course not. Obviously the endpoint returns 200 (or 201). Responses with error 500 obviously can also happen, because internal and unexpected errors can happen in the server.
So what's the point of listing some of responses and not others? And the listed status codes can just be "normally" interpreted - 404 is not found, so obviously a pet is not found.
But well, as I said, I'm not against it. we can implement it eventually so you can improve your Swagger specification, no problem.
Feature request:
2 Likes
This topic was automatically closed 60 minutes after the last reply. New replies are no longer allowed.