-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Multiple Examples with Different Parameters #310
Comments
Hey @scalabl3 , I love your way of thinking about this problem! Great stuff!! Out of curiosity, are familiar with MSON used for attributes description? Have you seen the proposal to use the MSON for parameters and headers description? I would like to hear your opinion on that if you would find a time... |
Yes I saw #58, which is what I was looking at to try to solve this variety of documentation. Multiple Requests/Responses are fine, except that you have to hit "show" to actually see them, but when you do that, you are just showing a code block with headers overridden. It's not easy to read or plainly visible (it feels more hidden). I like the idea of Request/Response pairs, but multiple example usages in my case are more frequently needed. I only illustrated one above, but I have many cases where there are varieties of parameters and formatting of parameters that end-users need to know and also have an example of, having a simple singular example only covers the simplest of api calls. Maybe there is a way to have Request/Response grouping be "nested" or "separate" based on the node level of its container? |
@scalabl3 I guess there are two things here:
Re 1. It is still open how Apiary docs will render multiple examples based on parameter values Re 2. API Blueprint is currently reference-like format. We have considered support for scenarios #21 but so far it wasn't a popular request. |
I like the proposal of @scalabl3 a lot. How can we help to get this implemented?
I suppose the proper why to this right now is to come up with an RFC, correct? |
I think this is almost implemented in the parser. Maybe @kylef or @pksunkara can point to the exact place where paramers-based response is being implementd
Yup. Make sure to check the #21 too |
@Perni1984 Yes, there was an accepted RFC 4: Request Parameters which has been implemented. Support for request parameters has been implemented in the master branch of drafter [via drafter#230]. We are planning to improve the support with additional warnings when the syntax is mis-used. If you want to use this functionality in your own tools, these parameters will be surfaced via the Refract API Description namespace and can be found under the |
I forgot to mention, the changes for the API Blueprint specification can be found at #293, merging this is pending a new release of the parser. |
+1 |
I am trying to figure out how to do list multiple examples with different parameter combinations and formatting for a single resource/request type that have consistent responses.
It's also ok if I supply parameter types above the examples, and then just put in examples more simply:
Simulated Rendered Example (this is how I wish it looked)
![](https://camo.githubusercontent.com/e1e12d884d2ca269ba8eb3fae7e860d7a8dd329cc955c7de152360d78f369fc3/687474703a2f2f676f6f676f2e6d652f335433443145337a3268316d2f496d616765253230323031362d30322d30332532306174253230312e33302e3235253230504d2e706e67)
The text was updated successfully, but these errors were encountered: