From 160ffe0a7a6cfad929db20949234be75ba1d878c Mon Sep 17 00:00:00 2001 From: Oh My Felix Date: Sun, 21 Jun 2026 21:21:15 +0000 Subject: [PATCH] Docs: move documentation to README. Co-authored-by: Felix --- .docs/README.md | 164 ----------------------------------------------- README.md | 166 +++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 158 insertions(+), 172 deletions(-) delete mode 100644 .docs/README.md diff --git a/.docs/README.md b/.docs/README.md deleted file mode 100644 index c5d1b8e..0000000 --- a/.docs/README.md +++ /dev/null @@ -1,164 +0,0 @@ -# Contributte\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.

- -## Content - -- [Content](#content) -- [Usage - runtime documentation](#usage---runtime-documentation) - + [GET routes](#get-routes) - + [PUT, POST, DELETE routes](#put--post--delete-routes) - + [Presenter code:](#presenter-code-) -- [Generating API documentation](#generating-api-documentation) - + [`?__apiDocuGenerate`](#----apidocugenerate-) -- [HTTP authorization](#http-authorization) - -## 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: - -```neon -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: - -```neon -apiDocu: - apiDir: "%wwwDir%/client-api" - httpAuth: - user: foo - password: bar -``` diff --git a/README.md b/README.md index 9adc679..62063f3 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,16 @@ Website 🚀 contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte

-## Usage +Generate API documentation for routes created using [ApiRouter](https://github.com/contributte/api-router), either from directly defined routes or from annotations. + +## Versions + +| State | Version | Branch | Nette | PHP | +|--------|---------|----------|--------|---------| +| dev | `^6.1` | `master` | `3.3+` | `>=8.2` | +| stable | `^6.0` | `master` | `3.3+` | `>=8.2` | + +## Installation To install the latest version of `contributte/api-docu` use [Composer](https://getcomposer.org). @@ -26,16 +35,157 @@ To install the latest version of `contributte/api-docu` use [Composer](https://g composer require contributte/api-docu ``` -## Documentation +## Usage -For details on how to use this package, check out our [documentation](.docs). +![Route docs](.docs/assets/route-docs.png) -## Versions +ApiDocu can show API documentation for the current route, if there is any. Visit the API URL and add a `?__apiDocu` parameter in your address bar. -| State | Version | Branch | Nette | PHP | -|--------|---------|----------|--------|---------| -| dev | `^6.1` | `master` | `3.3+` | `>=8.2` | -| stable | `^6.0` | `master` | `3.3+` | `>=8.2` | +### GET Routes + +Visit the API URL with the `?__apiDocu` query parameter. + +### PUT, POST, DELETE Routes + +Browsers can only match routes with the GET method directly. Change the route method using the `?__apiRouteMethod` query parameter. To visit DELETE route API documentation, use a URL such as `/users/10?__apiRouteMethod=DELETE&__apiDocu`. + +For 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) + +When you are directly on some API URL, you can use the `?__apiDocuGenerate` query parameter to generate whole application API documentation. All documentation files will be available in the directory specified by you. By default, the directory is: + +```neon +apiDocu: + apiDir: "%wwwDir%/api" + +extensions: + apiRouter: Contributte\ApiRouter\DI\ApiRouterExtension + apiDocu: Contributte\ApiDocu\DI\ApiDocuExtension +``` + +Example API generation trigger: `/api-router/api/books?__apiDocuGenerate`. + +## HTTP Authorization + +You can use HTTP authorization on your documentation sites: + +```neon +apiDocu: + apiDir: "%wwwDir%/client-api" + httpAuth: + user: foo + password: bar +``` ## Development