Contributte Api-docu
# Contributte\ApiDocu
ApiDocu can generate api documentation for routes created using ApiRouter (opens new window). It works either for directly defined routes or the ones defined via annotation.
# Content
# Usage - runtime documentation
# GET routes
ApiDocu can show you api documentation for current route, if there is any. Just visit the api url and add a ?__apiDocu parameter in you address bar.
# PUT, POST, DELETE routes
But you cat match only routes with GET method when you are comming through browser window. Route method can by changed using ?__apiRouteMethod query parameter. To visit PUT route api documentation you have to write something like that: /users/10?__apiRouteMethod=DELETE&__apiDocu. Here is an example: /api-router/api/users/8?__apiRouteMethod=PUT&__apiDocu.
# Presenter code:
<?php
namespace App\ResourcesModule\Presenters;
use Nette;
use Contributte\ApiRouter\ApiRoute;
/**
* API for managing users
*
* @ApiRoute(
* "/api-router/api/users[/<id>]",
* parameters={
* "id"={
* "requirement": "\d+",
* "type": "integer",
* "description": "User ID",
* "default": 10
* }
* },
* priority=1,
* format="json",
* section="Users",
* presenter="Resources:Users"
* )
*/
class UsersPresenter extends Nette\Application\UI\Presenter
{
/**
* Get user detail
*
* You **can** also write example json in the description
*
* <json>
* {
* "name": "John",
* "surname": "Doe",
* "age": 23,
* "hairCount": 123456,
* "parents": {{
* "name": "John",
* "surname": "Doe",
* "age": 53,
* "hairCount": 456
* }}
* }
* </json>
*
* @ApiRoute(
* "/api-router/api/users/<id>[/<foo>-<bar>]",
* parameters={
* "id"={
* "requirement": "\d+",
* "type": "integer",
* "description": "User ID",
* "default": 10
* }
* },
* method="GET",
* format="json",
* example={
* "name": "John",
* "surname": "Doe",
* "age": 23,
* "hairCount": 123456,
* "parents": {{
* "name": "John",
* "surname": "Doe",
* "age": 53,
* "hairCount": 456
* }}
* },
* tags={
* "public",
* "secured": "#e74c3c"
* },
* response_codes={
* 200="Success",
* 400="Error in authentication process",
* 401="Invalid authentication"
* }
* )
*/
public function actionRead($id, $foo = NULL, $bar = NULL)
{
$this->sendJson(['id' => $id, 'foo' => $foo, 'bar' => $bar]);
}
public function actionUpdate($id)
{
$this->sendJson(['id' => $id]);
}
public function actionDelete($id)
{
$this->sendJson(['id' => $id]);
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
# Generating API documentation
# ?__apiDocuGenerate
When you are directly on some api url, you can use query parameter ?__apiDocuGenerate for generating whole application api documentation. All documentation files will be available in directory specified by you. By default, the directory is:
apiDocu:
apiDir: "%wwwDir%/api"
extensions:
apiRouter: Contributte\ApiRouter\DI\ApiRouterExtension
apiDocu: Contributte\ApiDocu\DI\ApiDocuExtension
2
3
4
5
6
Example api generation trigger is here: /api-router/api/books?__apiDocuGenerate.
# HTTP authorization
You can use a HTTP authorization on your documentation sites:
apiDocu:
apiDir: "%wwwDir%/client-api"
httpAuth:
user: foo
password: bar
2
3
4
5