danielgtaylor / danielgtaylor/aglio

Multiple Examples with Different Parameters

Open
#229 4 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.