Skip to content

Commit 67b3a2a

Browse files
JackNetoJackNeto
committed
updated docs
1 parent aa91432 commit 67b3a2a

File tree

2 files changed

+151
-9
lines changed

2 files changed

+151
-9
lines changed

‎README.md

Lines changed: 145 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Bundle it:
1717

1818
Add [Twitter bootstrap](http://twitter.github.com/bootstrap) and [Google code pretifyer](http://google-code-prettify.googlecode.com/svn/trunk/README.html) to you CSS manifest file
1919

20-
``` css
20+
``` js
2121
//= require bootstrap
2222
//= require prettify
2323
```
@@ -32,12 +32,155 @@ Here's what you Javascript manifest file should look like
3232
//= require api_docs
3333
```
3434

35-
Add your API documentation files to the /doc folder and in your view do:
35+
Add your API documentation files to the /doc/api folder and in your view do:
3636

3737
``` ruby
3838
= render_api_docs %w{login users overview}
3939
```
4040

41+
## The API documentaion files
42+
43+
``` yaml
44+
'List':
45+
url: '/users'
46+
method: GET
47+
description: |
48+
Returns a list of users ordered by relationship:
49+
is_friends_with
50+
follows
51+
params:
52+
api_key:
53+
keyword: "a string of one or more words used to filter the users by first_name, last_name, username and email (optional)"
54+
success:
55+
response: 'HTTP/1.1 200 OK'
56+
data: |
57+
{
58+
"users": [
59+
{
60+
"id": 27,
61+
"first_name": "Andres",
62+
"last_name": "Aquino",
63+
"username": "eh_eh",
64+
"bio": "",
65+
"avatar_url": "http://.../thumb.jpg",
66+
"cover_photo_url": "http://.../thumb.jpg",
67+
"score": 0,
68+
"relationship": ["is_friends_with"],
69+
"created_at": "2011-06-13T00:28:36-04:00",
70+
"updated_at": "2012-04-26T20:21:43-04:00"
71+
},
72+
{
73+
"id": 3,
74+
"first_name": "Andrew",
75+
"last_name": "Peek",
76+
"username": "ap",
77+
"bio": "A dude.",
78+
"avatar_url": "http://.../thumb.jpg",
79+
"cover_photo_url": "http://.../thumb.jpg",
80+
"score": 0,
81+
"relationship": ["is_friends_with"],
82+
"created_at": "2011-06-13T00:28:36-04:00",
83+
"updated_at": "2012-04-26T20:21:43-04:00"
84+
},
85+
...
86+
]
87+
}
88+
curl: curl -i :api_url/v1/users?api_key=7gR9hZt3DBqcuzi2mZKN
89+
90+
# ------------------------------
91+
92+
'Show':
93+
url: '/users/:id'
94+
method: GET
95+
description: |
96+
Returns profile details for a specified user.
97+
<span class=label>NOTE</span> If showing details of another user the email is ommited
98+
<span class=label>TODO</span> response is missing the counters (notebooks, notes, comments, rocketed notes, followers, following, activity feed, notifications)
99+
params:
100+
api_key:
101+
id: the id of a user
102+
success:
103+
response: 'HTTP/1.1 200 OK'
104+
data: |
105+
{
106+
"user": {
107+
"id": 917,
108+
"api_key": "7gR9hZt3DBqcuzi2mZKN",
109+
"email": "[email protected]",
110+
"first_name": "John",
111+
"last_name": "Smith",
112+
"username": "john_smith",
113+
"bio": "",
114+
"avatar_url": ""http://.../photo.png",
115+
"cover_photo_url": null,
116+
"score": 0,
117+
"created_at": "2011-06-13T00:28:36-04:00",
118+
"updated_at": "2012-04-26T20:21:43-04:00"
119+
}
120+
}
121+
fail:
122+
response: 'HTTP/1.1 404 Not Found'
123+
data: |
124+
{
125+
"message": "User not found"
126+
}
127+
curl: curl -i :api_url/v1/users/197?api_key=2a10K5ipBd2qapJsPvCso90kMO
128+
129+
# ------------------------------
130+
131+
'Create':
132+
url: '/users'
133+
method: POST
134+
description: '[TODO] response is missing the counters (notebooks, notes, comments, rocketed notes, followers, following, activity feed, notifications)'
135+
params:
136+
user[first_name]:
137+
user[last_name]:
138+
user[email]:
139+
user[username]:
140+
user[password]:
141+
user[bio]:
142+
user[avatar]: "the user's avatar file"
143+
user[cover_photo]: "the user's cover photo file"
144+
success:
145+
response: 'HTTP/1.1 201 Created'
146+
data: |
147+
{
148+
"user": {
149+
"id": 917,
150+
"api_key": "7gR9hZt3DBqcuzi2mZKN",
151+
"email": "[email protected]",
152+
"first_name": "John",
153+
"last_name": "Smith",
154+
"username": "john_smith",
155+
"bio": "",
156+
"avatar_url": ""http://.../photo.png",
157+
"cover_photo_url": null,
158+
"score": 0,
159+
"created_at": "2011-06-13T00:28:36-04:00",
160+
"updated_at": "2012-04-26T20:21:43-04:00"
161+
}
162+
}
163+
fail:
164+
response: 'HTTP/1.1 422 Unprocessable Entity'
165+
data: |
166+
{
167+
"message": "Failed to create User",
168+
"errors" : {
169+
"email": "Email is invalid",
170+
...
171+
}
172+
}
173+
curl: |
174+
curl -i :api_url/v1/users \
175+
-F "user[first_name]=Jon" \
176+
-F "user[last_name]=Doe" \
177+
-F "user[email][email protected]" \
178+
-F "user[username]=jon2_doe" \
179+
-F "user[password]=passpass" \
180+
-F "user[avatar]=@test/fixtures/upload.png" \
181+
-F "user[cover_photo]=@test/fixtures/upload.png"
182+
```
183+
41184
42185
## Configuration
43186

‎api_docs.gemspec

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
99

1010
s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
1111
s.authors = ["Jack Neto", "The Working Group Inc."]
12-
s.date = %q{2012-05-01}
12+
s.date = %q{2012-05-02}
1313
s.description = %q{}
1414
s.email = %q{[email protected]}
1515
s.extra_rdoc_files = [
@@ -21,17 +21,16 @@ Gem::Specification.new do |s|
2121
"README.md",
2222
"Rakefile",
2323
"VERSION",
24-
"app/assets/images/whitey.png",
25-
"app/assets/javascripts/api_docs/application.js.coffee",
26-
"app/assets/stylesheets/api_docs/application.sass",
27-
"app/controllers/api_docs_controller.rb",
24+
"api_docs.gemspec",
25+
"app/assets/javascripts/api_docs.js.coffee",
26+
"app/assets/javascripts/prettify.js",
27+
"app/assets/stylesheets/prettify.css",
28+
"app/views/api_docs/_api_docs.html.haml",
2829
"app/views/api_docs/_curl.html.haml",
2930
"app/views/api_docs/_form.html.haml",
3031
"app/views/api_docs/_panel.html.haml",
3132
"app/views/api_docs/_params.html.haml",
3233
"app/views/api_docs/_response.html.haml",
33-
"app/views/api_docs/index.html.haml",
34-
"config/routes.rb",
3534
"lib/api_docs.rb",
3635
"lib/api_docs/configuration.rb",
3736
"lib/api_docs/engine.rb",

0 commit comments

Comments
 (0)