2017 © Pedro Peláez
 

library laravel-swagger

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

image

ronasit/laravel-swagger

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  • Tuesday, March 13, 2018
  • by Asxer
  • Repository
  • 3 Watchers
  • 9 Stars
  • 3,878 Installations
  • PHP
  • 2 Dependents
  • 0 Suggesters
  • 0 Forks
  • 1 Open issues
  • 15 Versions
  • 14 % Grown

The README.md

, (*1)

Laravel Swagger plugin

Total Downloads Latest Stable Version License , (*2)

Laravel Swagger Coverage Status, (*3)

Comparison to another documentation generators

LaravelSwagger Scramble
Force developers to write tests :white_check_mark: :x:
Guarantee that API works :white_check_mark: :x:
Works with any route types covered by tests :white_check_mark: :x:
Generate response schema using JSON Resource class :x: :white_check_mark:
Runtime documentation generation :x: :white_check_mark:

Introduction

This plugin is designed to generate documentation for your REST API during the passing PHPUnit tests., (*4)

Installation

  1. Install the package using the following command: composer require ronasit/laravel-swagger

Note, (*5)

For Laravel 5.5 or later the package will be auto-discovered. For older versions add the AutoDocServiceProvider to the providers array in config/app.php as follow:, (*6)

'providers' => [
      ...
      RonasIT\AutoDoc\AutoDocServiceProvider::class,
  ],
  
  1. Run
php artisan vendor:publish --provider=RonasIT\\AutoDoc\\AutoDocServiceProvider
  1. Add \RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class middleware to the global HTTP middleware list bootstrap\app.php:
    return Application::configure(basePath: dirname(__DIR__))
        ->withMiddleware(function (Middleware $middleware) {
            $middleware->use([
                ...
                \RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class,
            ]);
        });
  1. Add \RonasIT\AutoDoc\Traits\AutoDocTestCaseTrait trait to tests/TestCase.php, (*7)

  2. Configure documentation saving using one of the next ways:, (*8)

    • Add SwaggerExtension to the <extensions> block of your phpunit.xml. Please note that this way will be removed after updating PHPUnit up to 10 version (https://github.com/sebastianbergmann/phpunit/issues/4676)
    <phpunit>
      <extensions>
          <bootstrap class="RonasIT\AutoDoc\Support\PHPUnit\Extensions\SwaggerExtension"/>
      </extensions>
      <testsuites>
          <testsuite name="Feature">
              <directory suffix="Test.php">./tests/Feature</directory>
          </testsuite>
      </testsuites>
    </phpunit>
    
    • Call php artisan swagger:push-documentation console command after the tests stage in your CI/CD configuration

Usage

Basic usage

  1. Create request class:, (*9)

    <?php
    
    namespace App\Http\Requests;  
    
    use Illuminate\Foundation\Http\FormRequest;
    
    /**
    * @summary Update user
    *
    * @deprecated 
    *
    * @description
    * This request should be used for updating the user data
    *
    * @_204 Successful
    * 
    * @is_active will indicate whether the user is active or not
    */
    class UpdateUserDataRequest extends FormRequest
    {
        /**
         * Determine if the user is authorized to make this request.
         *
         * @return bool
         */
        public function authorize()
        {
            return true;
        }  
    
        /**
         * Validation Rules
         *
         * @return array
         */
        public function rules()
        {
            return [
                'name' => 'string',
                'is_active' => 'boolean',
                'age' => 'integer|nullable'
            ];
        }
    }
    
    

    Note, (*10)

    For correct working of plugin you'll have to dispose all the validation rules in the rules() method of your request class. Also, your request class must be connected to the controller via dependency injection. Plugin will take validation rules from the request class and generate fields description of input parameter., (*11)

  2. Create a controller and a method for your route:, (*12)

    <?php
    
    namespace App\Http\Controllers;
    
    use App\Http\Requests\Users\UpdateUserDataRequest;
    
    class UserController extends Controller
    {
        public function update(UpdateUserDataRequest $request, UserService $service, $id)
        {
            // do something here...
    
            return response('', Response::HTTP_NO_CONTENT);
        }
    }
    

    Note, (*13)

    Dependency injection of request class is optional but if it not presents, the "Parameters" block in the API documentation will be empty., (*14)

  3. Create test for API endpoint:, (*15)

    public function testUpdate()
    {
        $response = $this->json('put', '/users/1', [
            'name': 'Updated User',
            'is_active': true,
            'age': 22
        ]);
    
        $response->assertStatus(Response::HTTP_NO_CONTENT);
    }
    
  4. Run tests, (*16)

  5. Go to route defined in the auto-doc.route config
  6. Profit!, (*17)

    img.png, (*18)

Annotations

You can use the following annotations in your request classes to customize documentation of your API endpoints:, (*19)

  • @summary - short description of request
  • @description - implementation notes
  • @_204 - custom description of response code. You can specify any code as you want.
  • @some_field - description of the field from the rules method
  • @deprecated - mark route as deprecated

Note, (*20)

If you do not use request class, the summary and description and parameters will be empty., (*21)

Configs

  • auto-doc.route - route for generated documentation
  • auto-doc.basePath - root of your API

Custom driver

You can specify the way to collect and view documentation by creating your own custom driver., (*22)

You can find example of drivers here., (*23)

Viewing OpenAPI documentation

As of version 2.2, the package includes the ability to switch between OpenAPI documentation viewers. To access different viewers, modify the documentation_viewer configuration. This change is reflected immediately, without the need to rebuild the documentation file., (*24)

Merging additional documentations

The package supports the integration of the primary documentation with additional valid OpenAPI files specified in the additional_paths configuration., (*25)

Migration guides

3.0.1-beta, (*26)

Contributing

Thank you for considering contributing to Laravel Swagger plugin! The contribution guide can be found in the Contributing guide., (*27)

License

Laravel Swagger plugin is open-sourced software licensed under the MIT license., (*28)

The Versions

13/03 2018

dev-master

9999999-dev

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

13/03 2018

1.2.3

1.2.3.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

05/03 2018

1.2.2

1.2.2.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

23/08 2017

1.2.1

1.2.1.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

23/08 2017

1.2.0

1.2.0.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

21/08 2017

1.1.11

1.1.11.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

14/07 2017

1.1.9

1.1.9.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

08/07 2017

1.1.8

1.1.8.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

07/07 2017

1.1.7

1.1.7.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

14/06 2017

1.1.6

1.1.6.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

17/05 2017

1.1.5

1.1.5.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

28/04 2017

1.1.4

1.1.4.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

10/04 2017

1.1.3

1.1.3.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

05/04 2017

1.1.2

1.1.2.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation

05/04 2017

1.1.1

1.1.1.0

Provided middleware for generating of swagger-documentation file by run testing of RESTful API.

  Sources   Download

MIT

The Requires

 

by Roman Dubrovin

laravel testing swagger rest-api auto-documentation