Smartdocs is not display sample 200 response json payload

[#1]

We are just starting with our use of Apigee. One of the pieces of feedback that developers have is regarding smartdocs. When they go to view a method, they get description, parameters and error details. They don't get to see the sample 200 json response that we specified in the swagger documentation. Is there something that I'm missing? What's the point of going through a lot of trouble in specifying response objects in swagger if smartdocs doesn't display them 😞 .

[Marsh]

Just because it's in the OpenAPI Specification (new name of the Swagger spec) doesn't mean it's terrifically useful to developers! When we designed SmartDocs, we deliberately chose to emphasize error conditions under the assumption that a 200/201 response will be an obvious success based on the data and status code it returns. On the other hand, error states mean something is wrong, so those are much more critical to document.

We may address this is a future release if there is enough interest.

[#3]

I understand the importance of highlighting and showing the error codes that a developer can get when calling the API. The issue that I have is that we spent time developing our json schemas that we would return for APIs. For example, when an 400 error is thrown we don't just return a string saying "400 Bad Request". We return a json object with a human readable error message, developer error message and a url for more details. All this information is not displayed by the OpenAPI Sepcification (swagger.json file that was uploaded to smartdocs). My second issue with smartdocs is that we direct our developers to the portal and what they get when they click on a method is: description, resource url and parameters (if available). There's no way for a developer to view the data that is returned by an API unless they register an application and execute the curl commands to call the API. For APIs that require an approval, the developer would have to send out an email to ask what fields are returned by a given API. We want our documentation to be useful to developers so they can get what they need from it instead of having to contact us. For example, when you compare the api documentation of twilio ( https://www.twilio.com/docs/api/rest/call) and stripe ( https://stripe.com/docs/api#balance ) to smartdocs you can see a big difference in usefulness to developers. Both of these API docs tell the developer what JSON fields to expect from API calls. Sorry for the long rant, but I wanted to provide feedback. I'm hopeful that future versions of Smartdocs contain more useful information. In its current iteration, I'm stuck using Drupal nodes and blocks to supplement what should have been included by default 😞

[skarlovic]

I agree with what you said @jose.cedeno and I am struggling with the same issue right now, what approach did you go with to show response schemas/samples for 200 level responses? If you don't mind sharing. Just curious to hear what other teams are doing. Thanks.

[#5]

@jose.cedeno @skarlovic Even I am struggling with the same problem.
Please provide your feedback to idea I have suggested.

[#6]

I didn't end up implementing a solution. I have been busy with other projects and implementing APIs. Here is the two approaches that we started to explore:

* Use Drupal blocks and in the content of the block manually copy the swagger 200 response json body. This would require some theming to make sure the spacing and braces in the json body would look correct.

* We looked at using Slate as an alternative method to document our APIs: https://github.com/lord/slate. It is an open source project for us the big drawback is that is only for documentation and you cannot try the API. The fact that you could display sample api calls in a variety of languages was a big plus.

[#7]

Please add this feature.

Knowing what the api does under normal circumstances is crucial. Same applies to the request body that is never rendered as real documentation but just as example object to use with the cURL.

From a developer side, you need to be able to clarify what the request should look like