nhattuanbl/lara-swagger

Swagger ui doc for laravel

2.0 2024-10-17 15:50 UTC

This package is auto-updated.

Last update: 2024-12-17 09:05:17 UTC


README

Latest Version on Packagist Software License Total Downloads

Swagger ui doc for laravel 6,7 or 8

Requires

  • PHP: >=8.0
  • Laravel: latest version 6, 7, or 8

    Installation

    composer require nhattuanbl/lara-swagger
    
    php artisan vendor:publish --provider="LaraSwagger\LaraSwaggerServiceProvider" --tag="views"
    

    Edit: config/app.php

    'providers' => [
    ...
    \LaraSwagger\LaraSwaggerServiceProvider::class,
    ];
    

    Usage

  • Example route:
    Route::get('/', function () {
     return view('vendor/lara_swagger/lara_swagger');
    });
    

Route::get('/swagger.json', function (\LaraSwagger\LaraSwagger $laraSwagger) {

return response($laraSwagger->getDocs())->header('Content-Type', 'application/json');

});

Edit: `resources/views/vendor/lara_swagger/lara_swagger.blade.php`

window.onload = function() {

// Begin Swagger UI call region
const ui = SwaggerUIBundle({
    url: "{{ url('swagger.json') }}", // <=== change to your route
    dom_id: '#swagger-ui',
    deepLinking: true,
 - Create model and controller:

php artisan make:model Product --controller --resource


namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory; use Illuminate\Database\Eloquent\Model; use LaraSwagger\Attributes\LaraSwagger;

[LaraSwagger]

class Product extends Model {

use HasFactory;

}

![img](https://i.imgur.com/b1dwopy.jpg)

<details>
<summary>Parameters</summary>

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory; use Illuminate\Database\Eloquent\Model; use LaraSwagger\Attributes\Parameter; use LaraSwagger\Attributes\LaraSwagger;

/**

  • @property string name
  • @property int quantity */

    [

    LaraSwagger( // controller: CustomController::class, // tag: 'Product', // description: string|['get' => 'markdown support']

     hidden: ['isInStock'],
     readOnly: ['id'],
    

    ), Parameter(name: 'page', type: 'integer', required: true, default: 1, description: 'Pagination', minimum: 1), Parameter(name: 'soldOut', type: 'boolean'), Parameter(name: 'status', type: 'string', enum: ['pending', 'delivered']), ] class Product extends Model { use HasFactory;

    protected $fillable = [

     'email'
    

    ];

    protected $casts = [

     'quantity' => 'int'
    

    ];

    protected $hidden = [

     'hasCategory'
    

    ];

    protected $dates = [

     'created_at'
    

    ];

    public function isInStock(): bool {

     return false;
    

    }

    public function hasCategory(): bool {

     return true;
    

    } }

    ![img](https://i.imgur.com/JfWYz1G.png)
    </details>
    
Add auth ```php Route::get('/swagger.json', function (\LaraSwagger\LaraSwagger $laraSwagger) { $laraSwagger->info = [ 'title' => 'some title', 'description' => 'some desc', 'version' => '2.0', 'termsOfService' => 'https://google.com', 'contact' => [ 'name' => 'nhattuanbl', 'email' => 'nhattuanbl@gmail.com' ] ]; $laraSwagger->security = [ 'apiKey' => [ 'type' => 'apiKey', 'in' => 'header', 'name' => 'X-API-Key' ], 'appId' => [ 'type' => 'apiKey', 'in' => 'header', 'name' => 'X-APP-ID' ], 'OAuth2' => [ 'type' => 'oauth2', 'flows' => [ 'authorizationCode' => [ 'authorizationUrl' => 'https://example.com/oauth/authorize', 'tokenUrl' => 'https://example.com/oauth/token', 'scopes' => [ 'read' => 'Grants read access', 'write' => 'Grants write access', 'admin' => 'Grants access to admin operations' ] ] ] ] ]; $laraSwagger->callbackOperation = function(string $method, string $endpoint, array $swagger) { //hide all get method if ($method == 'get') { return null; } if ($endpoint == '/users/{id}' && $method == 'put') { $swagger['security'] = [ ['apiKey' => []], ['appId' => []], ['OAuth2' => ['read', 'write']], ]; } return $swagger; }; $servers = [ ['url' => 'v1', 'description' => 'api v1'], ['url' => 'v2'] ]; return response($laraSwagger->getDocs($servers))->header('Content-Type', 'application/json'); }); ```
Add parameter ```php