# 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

Route docs

# 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]);
	}

}
1
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

Docs

# ?__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
1
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
1
2
3
4
5