README

安装

composer require syn/laravel-swagger-json-api-generator 

发布文件

php artisan vendor:publish --provider=Syn\LaravelSwaggerJsonApiGenerator\Providers\LaravelSwaggerJsonApiGeneratorServiceProvider

团队将发布

• 配置文件 swagger-jsonapi-generator.php
• 目录 docs 用于存储自定义路径和 OpenApi 组件

非常重要！！！

在 config/filesystems.php 中添加新的文档存储驱动程序

    'docs' => [
        'driver' => 'local',
        'root' => docs_path(),
        'throw' => false,
    ],

基本使用

要生成 laravel-json-api/laravel 软件包路由的 JsonApi 规范文档，需要配置配置文件

config/swagger-jsonapi-generator.php

<?php


return [

    'title' => 'Backend',
    'version' => '1.0.0',
    'description' => 'Бэкенд тестового проекта',

    /**
     * Серверы спецификации
     *
     * - { url: 'https://:8000/', description: local }
     */
    'servers' => [
        ['url' => 'https://:8000/', 'description' => 'local'],
    ],

    /**
     * Здась описываются ресурсы которые
     * необходимо отрисовать в документации
     * {тип ресурса} => {схема ресурса / тэг который будет отображатся для кастомных методов}
     * 'auth' => 'auth' // регистрация тэга ресурса если у него нет схемы
     * 'users' => UserSchema::class // регистрация тэга ресурса через схему LaravelJsonApi пакета
     */
    'resources' => [
        'auth' => 'auth',
        'users' => App\JsonApi\V1\Users\UserSchema::class
    ],

    /**
     * Ссылка на сервер LaravelJsonApi
     *
     * Пример:
     * 'server' => App\JsonApi\V1\Server::class
     */
    'serverJsonApi' => App\JsonApi\V1\Server::class,

    /**
     * Названия ресурсов которые будут отображатся в группе
     *
     * Пример:
     * 'auth' => 'Аутентификация',
     * 'users' => 'Пользователи',
     */
    'resourceNames' => [
        'auth' => 'Аутентификация',
        'users' => 'Пользователи',
    ]
];

在资源模型中需要添加一个表示资源类型的常量

app/Models/User.php

 public const MODEL_TYPE = 'users';

最后，将所有字段方案的类替换为该软件包中的相应类

<?php

namespace App\JsonApi\V1\Users;

use App\Models\User;
use LaravelJsonApi\Eloquent\Contracts\Paginator;
use LaravelJsonApi\Eloquent\Pagination\PagePagination;
use LaravelJsonApi\Eloquent\Schema;
 - use LaravelJsonApi\Eloquent\Fields\Boolean;
 - use LaravelJsonApi\Eloquent\Fields\DateTime;
 - use LaravelJsonApi\Eloquent\Fields\ID;
 - use LaravelJsonApi\Eloquent\Fields\Relation\BelongsTo;
 - use LaravelJsonApi\Eloquent\Fields\Str;
 - use LaravelJsonApi\Eloquent\Filters\WhereIdIn;
 + use Syn\LaravelSwaggerJsonApiGenerator\Fields\Boolean;
 + use Syn\LaravelSwaggerJsonApiGenerator\Fields\DateTime;
 + use Syn\LaravelSwaggerJsonApiGenerator\Fields\ID;
 + use Syn\LaravelSwaggerJsonApiGenerator\Fields\Relation\BelongsTo;
 + use Syn\LaravelSwaggerJsonApiGenerator\Fields\Str;
 + use Syn\LaravelSwaggerJsonApiGenerator\Filters\WhereIdIn;

class UserSchema extends Schema
{

    /**
     * The model the schema corresponds to.
     *
     * @var string
     */
    public static string $model = User::class;

    /**
     * Get the resource fields.
     *
     * @return array
     */
    public function fields(): array
    {
        return [
            ID::make(),
            Str::make('name'),
            Str::make('email')
                ->typeUsing('string')
                ->example('test@test.ru')
                ->description('Email пользователя'),

            Boolean::make('is_active')
                ->typeUsing('boolean')
                ->example(false)
                ->description('Активный пользователь'),

            BelongsTo::make('profiles')
                ->relationshipModel(Profile::class),

            DateTime::make('createdAt')->sortable()->readOnly(),
            DateTime::make('updatedAt')->sortable()->readOnly(),
        ];
    }

    /**
     * Get the resource filters.
     *
     * @return array
     */
    public function filters(): array
    {
        return [
            WhereIdIn::make($this)
                ->typeUsing('string')
                ->example('1,2,3,4')
                ->description('фильтр по ID'),
        ];
    }

    /**
     * Get the resource paginator.
     *
     * @return Paginator|null
     */
    public function pagination(): ?Paginator
    {
        return PagePagination::make();
    }

}

生成文档的命令

php artisan docs:gen