Skip to main content
Version: 12.x

Documentation

info

This package is installed by default with an Apiato fresh installation.

The Documentation Generator Container is a package that generates API documentation for your API Endpoints. It uses ApiDocJs to generate the documentation.

It is recommended to read about the Public and Private routes before using this package.

Requirements​

This package depends on ApiDocJs. Make sure to install it in the project directory by running:

npm install apidoc

Installation​

composer require apiato/documentation-generator-container

Publishing Configs​

php artisan vendor:publish

Config file will be placed at app/Ship/Configs/vendor-documentation.php

Usage​

Write the DocBlocks​

Write the DocBlocks for your API Endpoints in your Route files.

info

For more info about the parameters check out ApiDocJs documentation.

/**
 * @apiGroup           Authentication
 * @apiName            UserLogin
 * @api                {post} /clients/web/login User Login
 * @apiDescription     Description Here....
 * @apiVersion         1.0.0
 * @apiPermission      none
 *
 * @apiHeader          Accept application/json
 *
 * @apiParam           {String}     email
 * @apiParam           {String}     password
 *
 * @apiSuccessExample  {json}       Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "data": {
 *       "id": "XbPW7awNkzl83LD6",
 *       "name": "Super Admin",
 *       "email": "[email protected]"
 *   }
 *
 * @apiErrorExample  {json}       Error-Response:
 *   {
 *      "message":"401 Credentials Incorrect.",
 *   }
 *
 * @apiErrorExample  {json}       Error-Response:
 *   {
 *      "message":"Invalid Input.",
 *      "errors":{
 *         "email":[
 *            "The email field is required."
 *         ]
 *      },
 *   }
 */

use App\Containers\AppSection\Authentication\UI\API\Controllers\Controller;
use Illuminate\Support\Facades\Route;

Route::post('clients/web/login', Controller::class);
note

All the Endpoint DocBlocks MUST be written inside Routes files, otherwise they won't be loaded.

Generate the Documentation​

You can generate the API documentation by running the following command:

php artisan apiato:apidoc
Error: ApiDoc not found

If you get the apidoc not found error, you need to update the executable path in the vendor-documentation.php config file.

  1. Publish the configs
  2. Edit the executable path to $(npm bin)/apidoc or to however you access the apidoc tool on your machine.
/*
|--------------------------------------------------------------------------
| Executable
|--------------------------------------------------------------------------
|
| Specify how you run or access the `apidoc` tool on your machine.
|
*/

'executable' => 'node_modules/.bin/apidoc',
// 'executable' => 'apidoc',

Visit Documentation URL's​

Visit the documentation URLs as shown in your terminal:

tip

Don't forget to regenerate the documentation after making changes to the DocBlocks.

Private Documentation Protection​

By default, this feature is disabled in local environment and enabled in production.
To change this behavior, Publish the configs and change protect-private-docs.

Private documentations route is protected with the auth:web middleware. You can grant users access to the protected docs by updating access-private-docs-roles and access-private-docs-permission values in documentation config. By default, users need access-private-docs permission to access private docs.

Documentation Header Localization​

The documentation header is in English en by default. To see the documentation header in another language, you can change the locale in the .env file.

APIDOC_LOCALE=ru

To see the list of supported locales, check the app/Containers/Vendor/Documentation/ApiDocJs/shared folder. If you want to add a new language, you can create a new file in the shared folder and submit a PR.