danielgtaylor / danielgtaylor/aglio
Multiple Examples with Different Parameters
- Dominant language
- CoffeeScript
- Stars
- 4.7k
- Forks
- 471
- PR merge metrics
- No merged PRs in 30d
Description
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.
```
## MyAPICall [/resource/{param1}/{param2}{?jsonp,userID}]
### Example 1 [GET]
+ Parameters
+ param1 (string, `demo`) - Blog Subsection
+ param2 (string, `posts`) - Resources requested, comma separated (%2C encoded comma)
+ jsonp (string, `0`) - jsonp callback identifier, use `0` if not using jsonp
+ userID (string, `1234`) - userID of the caller
### Example 2 [GET]
+ Parameters
+ param1 (string, `demo`) - Blog Subsection
+ param2 (string, `posts%2Ccomments`) - Resources requested, comma separated (%2C encoded comma), i.e. posts,comments is posts%2Ccomments
+ jsonp (string, `0`) - jsonp callback identifier, use `0` if not using jsonp
+ userID (string, `1234`) - userID of the caller
+ Response 200
...
+ Response 404
...
```
It's also ok if I supply parameter types above the examples, and then just put in examples more simply:
```
## MyAPICall [/resource/{param1}/{param2}{?jsonp,userID}]
+ Parameters
+ param1 (string) - Blog Subsection
+ param2 (string) - Resources requested, comma separated (%2C encoded comma)
+ jsonp (string) - jsonp callback identifier, use `0` if not using jsonp
+ userID (string) - userID of the caller
### Example 1 [GET]
+ Parameters
+ param1: `demo`
+ param2: `posts`
+ jsonp: `0`
+ userID: `1234`
### Example 2 [GET]
+ Parameters
+ param1: `demo`
+ param2: `posts%2Ccomments`
+ jsonp: `0`
+ userID: `1234`
+ Response 200
...
+ Response 404
...
```
**Simulated Rendered Example** (this is how I wish it looked)
Contributor guide
No contributing guide indexed for this repository
Research direction
The issue names no files, tests, or entry points; start by tracing how Aglio parses and renders API Blueprint examples. Done means a single resource or request can show multiple parameter combinations and consistent responses, including the two parameter layouts described.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- coffeescript
- Domain
- api, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100