Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Add expect responses section #50

Closed
wants to merge 2 commits into from

5 participants

@allenhuang

Add ExpectResponses in method to annotate the format and schema of response

@donaldpiret

This would be quite nice to have, +1

@darrylkuhn

Was this ever merged in or was an alternate method introduced? Definitely +1 if it's not...

@phairow
Owner

It's not yet added and this implementation cannot be merged as is. at this point the solution would likely make more sense if it leveraged the json schema support we recently added. closing this pull request and keeping the discussion on #16 alive since the feature is still desired. See the sample schema https://github.com/mashery/iodocs/blob/master/public/data/egnyte.json and notice the recently added schemas section and also notice that methods now have a request property that can reference a schema. we probably want a response property where we can reference response schemas and other desired settings for the response.

@phairow phairow closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Sep 28, 2012
  1. Fix some json syntax error

    Allen Huang authored
Commits on Oct 19, 2012
  1. @allenhuang
This page is out of date. Refresh to see the latest.
View
121 README.md
@@ -253,12 +253,12 @@ Line:
"oauth" : {
"type": "three-legged",
"requestURL": "https://api.twitter.com/oauth/request_token",
- "signinURL": "https://api.twitter.com/oauth/authorize?oauth_token="
+ "signinURL": "https://api.twitter.com/oauth/authorize?oauth_token=",
"accessURL": "https://api.twitter.com/oauth/access_token",
"version": "1.0",
- "crypt": "HMAC-SHA1",
- }
- "keyParam": "",
+ "crypt": "HMAC-SHA1"
+ },
+ "keyParam": ""
}
```
@@ -357,43 +357,77 @@ You should look at the *./public/data/* directory for examples.
"methods":[
{
"MethodName":"users/show",
- "Synopsis":"Returns extended user information",
- "HTTPMethod":"GET",
- "URI":"/users/show.json",
- "RequiresOAuth":"N",
- "parameters":[
- {
- "Name":"user_id",
- "Required":"Y",
- "Default":"",
- "Type":"string",
- "Description":"The ID of the user",
- },
- {
- "Name":"cereal",
- "Required":"Y",
- "Default":"fruitscoops",
- "Type":"enumerated",
- "EnumeratedList": [
- "fruitscoops",
- "sugarbombs",
- "frostedteeth"
- ],
- "EnumeratedDescription": {
- "fruitscoops": "Fruit Scoops (packed with fruit goodness)",
- "sugarbombs": "Sugar Bombs (filled with sugar)",
- "frostedteeth": "Frosted Teeth (sugar coating)"
- },
- "Description":"The type of cereal desired"
- },
- {
- "Name":"skip_status",
- "Required":"N",
- "Default":"",
- "Type":"boolean",
- "Description":"If true, status not included"
- }
+ "Synopsis":"Returns extended user information",
+ "HTTPMethod":"GET",
+ "URI":"/users/show.json",
+ "RequiresOAuth":"N",
+ "parameters":[
+ {
+ "Name":"user_id",
+ "Required":"Y",
+ "Default":"",
+ "Type":"string",
+ "Description":"The ID of the user",
+ },
+ {
+ "Name":"cereal",
+ "Required":"Y",
+ "Default":"fruitscoops",
+ "Type":"enumerated",
+ "EnumeratedList": [
+ "fruitscoops",
+ "sugarbombs",
+ "frostedteeth"
+ ],
+ "EnumeratedDescription": {
+ "fruitscoops": "Fruit Scoops (packed with fruit goodness)",
+ "sugarbombs": "Sugar Bombs (filled with sugar)",
+ "frostedteeth": "Frosted Teeth (sugar coating)"
+ },
+ "Description":"The type of cereal desired"
+ },
+ {
+ "Name":"skip_status",
+ "Required":"N",
+ "Default":"",
+ "Type":"boolean",
+ "Description":"If true, status not included"
+ }
+ ],
+ "ExpectResponses": [
+ {
+ "Format": "json",
+ "Schema": {
+ "type": "object",
+ "properties": {
+ "email": {
+ "type": "string",
+ "description": "User address",
+ "required":true
+ },
+ "phone": {
+ "type":"string",
+ "description":"User phone",
+ "required":true,
+ "format": "phone"
+ },
+ "habbits": {
+ "type":"array",
+ "description":"User habbits",
+ "required":false,
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ },
+ {
+ "Format": "xml",
+ "Schema": {}
+ }
]
+ }
}]
}
```
@@ -436,6 +470,13 @@ Line:
27. "Type" key value is *boolean* that will render a drop-down (select box) on the form for *true* and *false*.
+28. "ExpectResponses" key value is an array of JSON objects (each one being a response format). It's an optional.
+
+29. "Format" in "ExpectResponses" key value is a string to annotate the response format (Ex:josn, xml...etc)
+
+29. "Schema" in "ExpectResponses" key value is an object to describe the response schema. It's better to use public schema relative to the format (Ex:json-schema for json)
+
+
SUPPORT
=======
If you need any help with I/O Docs, you can reach out to us via the GitHub Issues page at:
View
13 public/javascripts/docs.js
@@ -149,6 +149,19 @@
$('div.fields', this.parentNode).slideToggle();
});
+ // Toggle ExpectResponses section
+ $('div.expect-responses h4').click(function(event) {
+ event.preventDefault();
+
+ $(this.parentNode).toggleClass('expanded');
+
+ $('div.fields', this.parentNode).slideToggle();
+
+ if($('div.fields').is(":visible")) {
+ prettyPrint();
+ }
+ });
+
// Auth with OAuth
$('#credentials').submit(function(event) {
event.preventDefault();
View
25 public/stylesheets/style.css
@@ -489,6 +489,31 @@ li {
margin-top: 14px;
}
+/* ExpectResponses */
+.method div.expect-responses h4 {
+ margin-top: 0;
+}
+
+.method div.expect-responses .fields {
+ display: none;
+ padding: 0 15px;
+ margin-bottom: 15px;
+}
+
+.method div.expect-responses .indicator {
+ border-width: 5px;
+ border-color: transparent transparent transparent #333;
+ border-style: solid;
+ display: block;
+ float: left;
+ margin: 11px 0 0 10px;
+}
+
+.method div.expect-responses.expanded .indicator {
+ border-color: #333 transparent transparent transparent;
+ margin-top: 14px;
+}
+
.method:first-of-type {
margin-top: 0;
}
View
20 views/api.jade
@@ -152,5 +152,25 @@ ul
a(href='#', class='remove') Remove
a(href='#', class='add-headers') Add Header
// Create header fields and button to add/remove headers.
+ - if (method.ExpectResponses && method.ExpectResponses.length > 0)
+ div.expect-responses
+ h4.title
+ div.indicator
+ span Expect Responses
+ div.fields
+ table
+ thead
+ tr
+ th Format
+ th Schema
+ tbody
+ - var responseCount =0
+ - each response in method.ExpectResponses
+ - responseCount++
+ div(id='response' + responseCount)
+ tr
+ td.format=response.Format
+ td.schema
+ pre(class='prettyprint')!=JSON.stringify(response.Schema, null, 2)
- if (!method['read-only'])
input(type='submit', id=method.MethodName, value='Try it!')
Something went wrong with that request. Please try again.