Laravel 8 установка OpenAPI (Swagger)

Установка

Библиотека находится на гите. Там перейдите в Installation & Configuration и выберете свою версию ларки. Затем через консоль введи выбранную команду.

composer require "darkaonline/l5-swagger"

если появилась ошибка:

Your requirements could not be resolved to an installable set of packages.

Problem 1
– Root composer.json requires php ^8.0 but your php version (7.4.20) does not satisfy that requirement.
Problem 2
– psr/log 2.0.0 requires php >=8.0.0 -> your php version (7.4.20) does not satisfy that requirement.
– laravel/framework v8.70.2 requires psr/log ^1.0 || ^2.0 -> satisfiable by psr/log[2.0.0].
– laravel/framework is locked to version v8.70.2 and an update of this package was not requested.

Installation failed, reverting ./composer.json and ./composer.lock to their original content.

Загляните в свой composer.json и выставите:

"require": {
"php": "^7.3|^8.0",

Затем обновите composer update. После чего пробуйте снова установить пакет.

Затем пропишите в файле config/app ->

'providers' => [
     L5Swagger\L5SwaggerServiceProvider::class

И введите в консоли команду:

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

Настройка

Переходим в config/l5-swagger.php

Ищем блок в самом низу “Uncomment to add constants which can be used in annotations”.

'constants' => [
         'L5_SWAGGER_CONST_HOST' => env('L5_SWAGGER_CONST_HOST', 'http://my-default-host.com'),
         'L5_SWAGGER_CONST_HOST_V2' => env('L5_SWAGGER_CONST_HOST_V2', 'http://my-default-host.com'),
         'L5_SWAGGER_CONST_EMAIL' => env('MAIL_FROM_ADDRESS', 'no-reply@example.com'),
         ],

Первая и вторая строчка отвечает за разные версии API. Третья строка нужна для email адреса. Теперь откроем файл .env

Кофигурация

Первоначально нужно описать стандартный контролер. Открываем app/Http/Controllers/Controller.php

<?php

namespace App\Http\Controllers;

use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Routing\Controller as BaseController;

class Controller extends BaseController
{
    /**
     * @OA\Info(
     *      version="1.0.0",
     *      title="OpenApi Documentation",
     *      description="Документация для микро сервиса",
     *      @OA\Contact(
     *          email=L5_SWAGGER_CONST_EMAIL
     *      )
     * )
     *
     * @OA\Server(
     *      url=L5_SWAGGER_CONST_HOST,
     *      description="Основной API"
     * )
     * @OA\Server(
     *      url=L5_SWAGGER_CONST_HOST_V2,
     *      description="Для Логирования"
     * )
     *
     * @OA\Tag(
     *     name="Channels",
     *     description="Работа с каналами"
     * )
     */
    
    use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
}

Описываем модель, в моем случае она называется Channel.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

/**
 * @OA\Schema(
 *     title="Channel",
 *     description="Channel model",
 *     @OA\Xml(
 *         name="Channel"
 *     )
 * )
 */
class Channel extends Model
{
    /**
     * @OA\Property(
     *     title="ID",
     *     description="ID",
     *     format="int64",
     *     example=1
     * )
     *
     * @var bigInteger
     */
    private $id;
    /**
     * @OA\Property(
     *      title="Alias",
     *      description="Псевдоним канала",
     *      example="email"
     * )
     *
     * @var string
     */
    private $alias;
    /**
     * @OA\Property(
     *      title="Name",
     *      description="Название канала",
     *      example="E-mail"
     * )
     *
     * @var string
     */
    private $name;
    /**
     * @OA\Property(
     *      title="Is Active",
     *      description="Активный канала",
     *      example="true"
     * )
     *
     * @var boolean
     */
    private $is_active;
    /**
     * @OA\Property(
     *      title="Default Driver Alias",
     *      description="Драйвер по умолчанию на этом канале",
     *      example="mailtrap"h
     * )
     *
     * @var string
     */
    private $default_driver_alias;
    /**
     * @OA\Property(
     *     title="Created at",
     *     description="Created at",
     *     example="2020-01-27 17:50:45",
     *     format="datetime",
     *     type="string"
     * )
     */
    private $created_at;
    /**
     * @OA\Property(
     *     title="Updated at",
     *     description="Updated at",
     *     example="2020-01-27 17:50:45",
     *     format="datetime",
     *     type="string"
     * )
     */
    private $updated_at;

    protected $table = 'channels';
    
}

Описываем контроллер, в моем случаи ChannelController.

namespace App\Http\Controllers;

class ChannelController extends Controller
{
    /**
     * @OA\Get(
     *      path="/channels/{alias}",
     *      operationId="getListAvailableChannel",
     *      tags={"Channels"},
     *      summary="Получение списка доступных драйверов для канала",
     *      description="Метод возвращает данные ...",
     *     @OA\Parameter(
     *          name="alias",
     *          description="Alias канала (email)",
     *          required=true,
     *          in="path",
     *          @OA\Schema(
     *              type="string"
     *          )
     *      ),
     *     @OA\Response(
     *          response=200,
     *          description="Successful operation",
     *     @OA\JsonContent(ref="#/components/schemas/Channel")
     *       ),
     *     )
     */
    public function getListAvailableChannel()
    {
        //...
    }

    /**
     * * @OA\Get(
     *      path="/channels/",
     *      operationId="getChannels",
     *      tags={"Channels"},
     *      summary="Получить список всех доступных каналов",
     *      description="Получаем список всех доступных каналов",
     *     @OA\Response(
     *         response=200,
     *          description="successful operation",
     *          @OA\JsonContent(ref="#/components/schemas/Channel")
     *       ),
     *      @OA\Response(
     *         response=400,-n
     *         description="Invalid ID supplied"
     *      )
     *     )
     */
    public function getChannels()
    {
        //...
    }
}

НУ, а теперь запускаем эту команду в консоли и переходим по адресу /api/documentation

php artisan l5-swagger:generate

Возможно у вас как и у меня при запуске /api/documentation, откроется пустая страница, если нажать на странице F12 и перейти в консоль то вы увидите ошибки, которые сообщают, что не смог загрузить скрипты, т.к. их нет. Для решения этой проблемны переходим в public и создаем руками каталог public/docs/asset.

Затем переходим \vendor\swagger-api\swagger-ui\dist и все из нее копируем в ранее созданную папку.

Предыдущая

ПрограммированиеНастройка Web сервера на Centos 7 от А до Я

Следующая

ПрограммированиеМои настройки PHPStorm