README

This library is designed to gather information passing the features tests and generate documentation about your API. The principle of operation is based on the fact that the special Middleware installed on the Route for which you want to collect information that after the successful completion of all tests generated Swagger-file. In addition this plug-in is able to draw Swagger-template to display the generated documentation for a config.

Installation

Composer

composer require apoplavs/laravel-swagger

Laravel

add Apoplavs\Support\AutoDoc\AutoDocServiceProvider::class, to providers in config/app.php
run php artisan vendor:publish

Plugin

Add middleware \Apoplavs\Support\AutoDoc\Http\Middleware\AutoDocMiddleware::class to Http/Kernel.php.
Use \Apoplavs\Support\AutoDoc\Tests\AutoDocTestCaseTrait in your TestCase in tests/TestCase.php
In config/auto-doc.php you can specify enabling of plugin, info of your project, some defaults descriptions and route for rendering of documentation.

In .env file you should add following lines

AUTODOC_ENABLED=true
LOCAL_DATA_COLLECTOR_PROD_PATH=/example-folder/documentation.json
LOCAL_DATA_COLLECTOR_TEMP_PATH=/tmp/documentation.json

AUTODOC_ENABLED - enable or disable generate of documentation when passing a tests

LOCAL_DATA_COLLECTOR_..._PATH - custom path to your generated documentation file

You can disable autodoc for one test, just need before running test, set AutoDocMiddleware::$skipped = true;

Usages

For correct working of plugin you have to dispose all the validation rules in the rules() method of class YourRequest, which must be connected to the controller via DependencyInjection. In annotation of custom request you can specify summary and description of this request. Plugin will take validation rules from your request and use it as description of input parameter. If you want to set to common description of your API endpoints you can rewrite swagger-description.blade.php in your views and customize as you want. It will be render as blade template.

Example

<?php

namespace App\Http\Requests;  

use Illuminate\Foundation\Http\FormRequest;

/**
 * @summary Updating of user
 * @security false
 *
 * @description
 *  This request mostly needed to specity flags <strong>free_comparison</strong> and 
 *  <strong>all_cities_available</strong> of user
 *
 * @_204 Successful MF!
 */
class UpdateUserDataRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     *
     * @return bool
     */
    public function authorize()
    {
        return true;
    }  
  
    /**
     * Get the validation rules that apply to the request.
     *
     * @return array
     */
    public function rules()
    {
        return [
            'all_cities_available' => 'boolean',
            'free_comparison' => 'boolean'
        ];
    }
}

@summary - short description of request
@description - Implementation Notes
@skip-autodoc true - skip generate documentation for this request
@_204 - Custom description of code of response. You can specify any code as you want.
@security - ['bearerAuth', 'basicAuth', 'ApiKeyAuth', false] Depending on what you need null - disable of security for this request (when in common it set); ['bearerAuth', 'basicAuth', 'ApiKeyAuth'] - set specific type of security for this request

If you do not create a class Request, the summary, Implementation Notes and parameters will be empty. Plugin will collect codes and examples of responses only.

If you do not create annotations to request summary will generate automatically from Name of Request. For example request UpdateUserDataRequest will have summary Update user data request.

If you do not create annotations for descriptions of codes it will be generated automatically the following priorities:

Annotations of request
Default description from auto-doc.defaults.code-descriptions.{$code}
Descriptions from Symfony\Component\HttpFoundation\Response::$statusTexts

Note about configs:

auto-doc.route - it's a route where will be located generated documentation
auto-doc.basePath - common route where located root of your all API
auto-doc.info - common info about your documentation
auto-doc.servers - list of which (hosts) you can use when you test your endpoints
auto-doc.basePath - base path for your API routes, this will be considered as common path of your endpoints
auto-doc.security - type of authorization to your API routes. Available values: "bearerAuth", "basicAuth", "ApiKeyAuth", ""
auto-doc.defaults.code-descriptions - custom description of your API responses. For example, if when test passed and API endpoint return code 200, by default as description will be write "OK" but if you add to this array element '200' => 'Custom description'. When your API endpoint return code 200, as description will be write "Custom description"
auto-doc.defaults.headers - Default headers for add to each requests.
auto-doc.data_collector - it's a type of collect your document with API documentation. Thin library support JSON and YAML types. If you want to use YAMLDataCollector you must install yaml extension in your PHP https://www.php.net/manual/en/yaml.setup.php
auto-doc.enabled - it's just a flag enable (true) or disable (false) generate documentation when run tests

Also you can specify way to collect documentation by creating your custom data collector class.

This plugin based on https://github.com/RonasIT/laravel-swagger

apoplavs / laravel-autodoc

Maintainers

Details