sphinxcontrib.httpdomain — Documenting RESTful HTTP APIs¶
Directives¶
-
PATCH/users/(int: user_id)/posts/(tag)¶
-
GET/users/(int: user_id)/posts/(tag)¶
-
HEAD/users/(int: user_id)/posts/(tag)¶
-
POST/users/(int: user_id)/posts/(tag)¶
-
PUT/users/(int: user_id)/posts/(tag)¶
-
DELETE/users/(int: user_id)/posts/(tag)¶
-
TRACE/users/(int: user_id)/posts/(tag)¶
-
CONNECT/users/(int: user_id)/posts/(tag)¶
-
COPY/users/(int: user_id)/posts/(tag)¶
Sourcecode¶
GET /users/123/posts/web HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
[
{
"post_id": 12345,
"author_id": 123,
"tags": ["server", "web"],
"subject": "I tried Nginx"
},
{
"post_id": 12346,
"author_id": 123,
"tags": ["html5", "standards", "web"],
"subject": "We go to HTML 5"
}
]
Resource fields¶
-
GET/foo¶ Query Parameters: - resource – description for
resource
Status Codes: - 200 OK – description for 200
- 404 Not Found – description for 404
- resource – description for
-
GET/short-syntax¶ Request Headers: - Accept – application/json
Request JSON Object: - foo (string) – Foo key value
- bar (number) – Bar key value
Response Headers: - Content-Type – application/json
Response JSON Array of Objects: - baz (string) – Some baz field
Status Codes: - 200 OK – Success
Roles¶
Referring to existing directives¶
PATCH /users/(int:user_id)/posts/(tag)
OPTIONS /users/(int:user_id)/posts/(tag)
GET /users/(int:user_id)/posts/(tag)
HEAD /users/(int:user_id)/posts/(tag)
POST /users/(int:user_id)/posts/(tag)
PUT /users/(int:user_id)/posts/(tag)
DELETE /users/(int:user_id)/posts/(tag)
Here be Errors!¶
A request with method foo followed by bar and x-baz headers receives response with 42 Answer status code.
sphinxcontrib.autohttp.flask — Exporting API reference from Flask app¶
Basic option¶
-
GET/¶ Home page.
-
GET/(user)/posts/(int: post_id)¶ User’s post.
Parameters: - user – user login name
- post_id – post unique id
Status Codes: - 200 OK – when user and post exists
- 404 Not Found – when user and post doesn’t exist
-
GET/(user)¶ User profile page.
Parameters: - user – user login name
Status Codes: - 200 OK – when user exists
- 404 Not Found – when user doesn’t exist
Basic option with empty args¶
-
GET/¶ Home page.
-
GET/(user)/posts/(int: post_id)¶ User’s post.
Parameters: - user – user login name
- post_id – post unique id
Status Codes: - 200 OK – when user and post exists
- 404 Not Found – when user and post doesn’t exist
-
GET/(user)¶ User profile page.
Parameters: - user – user login name
Status Codes: - 200 OK – when user exists
- 404 Not Found – when user doesn’t exist
Filter some endpoints¶
-
GET/(user)¶ User profile page.
Parameters: - user – user login name
Status Codes: - 200 OK – when user exists
- 404 Not Found – when user doesn’t exist
-
GET/(user)/posts/(int: post_id)¶ User’s post.
Parameters: - user – user login name
- post_id – post unique id
Status Codes: - 200 OK – when user and post exists
- 404 Not Found – when user and post doesn’t exist
Documenting by non-ASCII characters¶
-
GET/¶ 홈 페이지.
-
GET/(user)/posts/(int: post_id)¶ 사용자의 게시물.
Parameters: - user – 사용자 접속명
- post_id – 게시물의 고유 번호
Status Codes: - 200 OK – 사용자와 게시물이 존재함
- 404 Not Found – 사용자 혹은 게시물이 존재하지 않음
-
GET/(user)¶ 사용자 정보 페이지.
Parameters: - user – 사용자 접속명
Status Codes: - 200 OK – 사용자가 존재함
- 404 Not Found – 사용자가 존재하지 않음