diff --git a/.docs/README.md b/.docs/README.md new file mode 100644 index 0000000..8345104 --- /dev/null +++ b/.docs/README.md @@ -0,0 +1,162 @@ +# ApiDocu + +ApiDocu can generate api documentation for routes created using [ApiRouter](https://github.com/contributte/api-router). It works either for directly defined routes or the ones defined via annotation.

+ +## Installing ApiDocu + +ApiDocu is available through composer package `contributte/api-docu`: + +``` +composer require contributte/api-docu +``` + +## Usage - runtime documentation + +![Route docs](assets/route-docs.png) + +### 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 +]", + * 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 + * + * + * { + * "name": "John", + * "surname": "Doe", + * "age": 23, + * "hairCount": 123456, + * "parents": {{ + * "name": "John", + * "surname": "Doe", + * "age": 53, + * "hairCount": 456 + * }} + * } + * + * + * @ApiRoute( + * "/api-router/api/users/[/-]", + * 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]); + } + +} +``` + +## Generating API documentation + +![Docs](assets/docs.png) + +### `?__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 +``` + +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 +``` diff --git a/docs/assets/docs.png b/.docs/assets/docs.png similarity index 100% rename from docs/assets/docs.png rename to .docs/assets/docs.png diff --git a/docs/assets/route-docs.png b/.docs/assets/route-docs.png similarity index 100% rename from docs/assets/route-docs.png rename to .docs/assets/route-docs.png diff --git a/README.md b/README.md index cb2713f..fc187c8 100644 --- a/README.md +++ b/README.md @@ -1,168 +1,48 @@ -[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/ublaboo/api-docu/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/ublaboo/api-docu/?branch=master) -[![Latest Stable Version](https://poser.pugx.org/ublaboo/api-docu/v/stable)](https://packagist.org/packages/ublaboo/api-docu) -[![License](https://poser.pugx.org/ublaboo/api-docu/license)](https://packagist.org/packages/ublaboo/api-docu) -[![Total Downloads](https://poser.pugx.org/ublaboo/api-docu/downloads)](https://packagist.org/packages/ublaboo/api-docu) -[![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/ublaboo/help) - -# ApiDocu - -ApiDocu can generate api documentation for routes created using [ApiRouter](https://github.com/contributte/api-router). It works either for directly defined routes or the ones defined via annotation.

- -## Installing ApiDocu - -ApiDocu is available through composer package `ublaboo/api-docu`: - -``` -composer require ublaboo/api-docu -``` - -## Usage - runtime documentation - -![Route docs](docs/assets/route-docs.png) - -### 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 -]", - * 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 - * - * - * { - * "name": "John", - * "surname": "Doe", - * "age": 23, - * "hairCount": 123456, - * "parents": {{ - * "name": "John", - * "surname": "Doe", - * "age": 53, - * "hairCount": 456 - * }} - * } - * - * - * @ApiRoute( - * "/api-router/api/users/[/-]", - * 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]); - } - -} -``` - -## Generating API documentation - -![Docs](docs/assets/docs.png) - -### `?__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: Ublaboo\ApiRouter\DI\ApiRouterExtension - apiDocu: Ublaboo\ApiDocu\DI\ApiDocuExtension -``` - -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 -``` +# RabbitMQ + +Ultra easy-to-use [`RabbitMQ`](https://www.rabbitmq.com/) implementation for [`Nette Framework`](https://github.com/nette/). + +[![Build Status](https://img.shields.io/travis/contributte/api-docu.svg?style=flat-square)](https://travis-ci.org/contributte/api-docu) +[![Code coverage](https://img.shields.io/coveralls/contributte/api-docu.svg?style=flat-square)](https://coveralls.io/r/contributte/api-docu) +[![Licence](https://img.shields.io/packagist/l/contributte/api-docu.svg?style=flat-square)](https://packagist.org/packages/contributte/api-docu) +[![Downloads this Month](https://img.shields.io/packagist/dm/contributte/api-docu.svg?style=flat-square)](https://packagist.org/packages/contributte/api-docu) +[![Downloads total](https://img.shields.io/packagist/dt/contributte/api-docu.svg?style=flat-square)](https://packagist.org/packages/contributte/api-docu) +[![Latest stable](https://img.shields.io/packagist/v/contributte/api-docu.svg?style=flat-square)](https://packagist.org/packages/contributte/api-docu) +[![PHPStan](https://img.shields.io/badge/PHPStan-enabled-brightgreen.svg?style=flat-square)](https://github.com/phpstan/phpstan) + +![](https://github.com/contributte/api-docu/blob/master/.docs/assets/route-docs.png "Route docs") + +## Discussion / Help + +[![Join the chat](https://img.shields.io/gitter/room/contributte/contributte.svg?style=flat-square)](http://bit.ly/ctteg) + +## Documentation + +- [Installing ApiDocu](.docs/README.md#installing-apidocu) +- [Usage - runtime documentation](.docs/README.md#usage---runtime-documentation) +- [Generating API documentation](.docs/README.md#generating-api-documentation) +- [HTTP authorization](.docs/README.md#http-authorization) + +## Versions +z +| State | Version | Branch | Nette | PHP | +|--------|--------------|----------|--------|---------| +| stable | `^3.0.0` | `master` | `3.0+` | `^7.1` | + +## Maintainers + + + + + + + +
+ + + +
+ Pavel Janda +
+ +Thank you for testing, reporting and contributing. diff --git a/composer.json b/composer.json index 852851a..fe83aae 100644 --- a/composer.json +++ b/composer.json @@ -1,12 +1,12 @@ { - "name": "ublaboo/api-docu", + "name": "contributte/api-docu", "type": "library", "description": "Documentation generating for ApiRouter routes - awesome runtime documentation", "keywords": ["rest", "api", "documentation", "docu", "apidocu", "routes", "nette"], - "homepage": "https://ublaboo.org/api-docu", + "homepage": "https://github.com/contributte/api-docu", "license": ["MIT"], "support": { - "issues": "https://github.com/ublaboo/api-docu/issues" + "issues": "https://github.com/contributte/api-docu/issues" }, "authors": [ { @@ -16,12 +16,12 @@ ], "autoload": { "psr-4": { - "Ublaboo\\ApiDocu\\": "src/" + "Contributte\\ApiDocu\\": "src/" } }, "autoload-dev": { "psr-4": { - "Ublaboo\\ApiDocu\\Tests\\": "tests" + "Contributte\\ApiDocu\\Tests\\": "tests" } }, "require": { @@ -30,7 +30,7 @@ "nette/application": "^3.0", "nette/di": "^3.0", "latte/latte": "^2.6", - "ublaboo/api-router": "~3.0.0" + "contributte/api-router": "~4.0.0" }, "require-dev": { "nette/tester": "^2.2", diff --git a/src/DI/ApiDocuExtension.php b/src/DI/ApiDocuExtension.php index 4d18b6b..f6f3b5e 100644 --- a/src/DI/ApiDocuExtension.php +++ b/src/DI/ApiDocuExtension.php @@ -2,19 +2,13 @@ declare(strict_types=1); -/** - * @copyright Copyright (c) 2016 ublaboo - * @author Pavel Janda - * @package Ublaboo - */ - -namespace Ublaboo\ApiDocu\DI; +namespace Contributte\ApiDocu\DI; use Nette\DI\CompilerExtension; use Nette\DI\Helpers; use Nette\PhpGenerator\ClassType; -use Ublaboo\ApiDocu\Generator; -use Ublaboo\ApiDocu\Starter; +use Contributte\ApiDocu\Generator; +use Contributte\ApiDocu\Starter; class ApiDocuExtension extends CompilerExtension { diff --git a/src/Generator.php b/src/Generator.php index 2d8251c..985428c 100644 --- a/src/Generator.php +++ b/src/Generator.php @@ -2,13 +2,7 @@ declare(strict_types=1); -/** - * @copyright Copyright (c) 2016 ublaboo - * @author Pavel Janda - * @package Ublaboo - */ - -namespace Ublaboo\ApiDocu; +namespace Contributte\ApiDocu; use Nette\Application\IRouter; use Nette\Application\Request; @@ -16,7 +10,7 @@ use Nette\Bridges\ApplicationLatte\Template; use Nette\Http; use Tracy\Debugger; -use Ublaboo\ApiRouter\ApiRoute; +use Contributte\ApiRouter\ApiRoute; class Generator { @@ -158,7 +152,7 @@ public function createTemplate(string $which): Template throw new \UnexpectedValueException; } - $template->addFilter(null, 'Ublaboo\ApiDocu\TemplateFilters::common'); + $template->addFilter(null, 'Contributte\ApiDocu\TemplateFilters::common'); $template->setFile(__DIR__ . '/templates/' . $which); diff --git a/src/Starter.php b/src/Starter.php index 690dfcf..afa1c5c 100644 --- a/src/Starter.php +++ b/src/Starter.php @@ -2,18 +2,12 @@ declare(strict_types=1); -/** - * @copyright Copyright (c) 2016 ublaboo - * @author Pavel Janda - * @package Ublaboo - */ - -namespace Ublaboo\ApiDocu; +namespace Contributte\ApiDocu; use Nette\Application\IRouter; use Nette\Application\Request; use Nette\Application\Routers\RouteList; -use Ublaboo\ApiRouter\ApiRoute; +use Contributte\ApiRouter\ApiRoute; class Starter { diff --git a/src/TemplateFilters.php b/src/TemplateFilters.php index 7d5df3a..d8ed10e 100644 --- a/src/TemplateFilters.php +++ b/src/TemplateFilters.php @@ -2,13 +2,7 @@ declare(strict_types=1); -/** - * @copyright Copyright (c) 2016 ublaboo - * @author Pavel Janda - * @package Ublaboo - */ - -namespace Ublaboo\ApiDocu; +namespace Contributte\ApiDocu; class TemplateFilters { diff --git a/src/templates/api_docu_matched.latte b/src/templates/api_docu_matched.latte index c7f396c..5c044e8 100644 --- a/src/templates/api_docu_matched.latte +++ b/src/templates/api_docu_matched.latte @@ -1,7 +1,7 @@ {extends 'api_docu_base.latte'} {** - * @param $route Ublaboo\ApiRouter\ApiRoute + * @param $route Contributte\ApiRouter\ApiRoute * @param $requestParameters array *} diff --git a/src/templates/api_docu_one.latte b/src/templates/api_docu_one.latte index 3ec3823..d376f6a 100644 --- a/src/templates/api_docu_one.latte +++ b/src/templates/api_docu_one.latte @@ -1,7 +1,7 @@ {extends 'api_docu_base.latte'} {** - * @param $route Ublaboo\ApiRouter\ApiRoute + * @param $route Contributte\ApiRouter\ApiRoute *} {var $parameters = $route->getParameters()} diff --git a/src/templates/api_docu_success.latte b/src/templates/api_docu_success.latte index 1bf83cb..1337c5e 100644 --- a/src/templates/api_docu_success.latte +++ b/src/templates/api_docu_success.latte @@ -1,7 +1,7 @@ {extends 'api_docu_base.latte'} {** - * @param $route Ublaboo\ApiRouter\ApiRoute + * @param $route Contributte\ApiRouter\ApiRoute * @param $request Nette\Application\Request *}