README

This plugin is designed to gather information and generate documentation about your Rest-Api while passing the tests. 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 tenantcloud/laravel-auto-generate-swagger

Laravel

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

Plugin

Add middleware \RonasIT\Support\AutoDoc\Http\Middleware\AutoDocMiddleware::class to Http/Kernel.php.
Use \RonasIT\Support\AutoDoc\Tests\AutoDocTestCaseTrait in your TestCase in tests/TestCase.php
In config/swagger.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 LOCAL_DATA_COLLECTOR_PROD_PATH=/example-folder/documentation.json LOCAL_DATA_COLLECTOR_TEMP_PATH=/tmp/documentation.json

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. Plugin will take validation rules from your request and use it as description of input parameter.

Example

<?php

namespace App\Http\Requests;  

use Illuminate\Foundation\Http\FormRequest;

/**
 * @summary Updating of user
 *
 * @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'
        ];
    }
}

In annotation of custom request you can specify summary and description of this request.

<?php

namespace App\Http\Controllers;  

use App\Http\Requests\UpdateRequest;

class UpdateController
{ 

/**
 * @tag json-api
 * @summary Updating of user
 *
 * @description
 *  This request mostly needed to specity flags <strong>free_comparison</strong> and 
 *  <strong>all_cities_available</strong> of user
 *
 * @_204 Successful MF!
 */
   public function update(int $id, UpdateRequest $request)
   {
       //...
   }
}

@tag - add tag for request
@summary - short description of request
@description - Implementation Notes
@_204 - Custom description of code of response. You can specify any code as you want.

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 swagger.defaults.code-descriptions.{$code}
Descriptions from Symfony\Component\HttpFoundation\Response::$statusTexts

Note about configs:

swagger.route - it's a route where will be located generated documentation
swagger.basePath - it's a route where located root of your api

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

tenantcloud / laravel-auto-generate-swagger

Maintainers

Details