README

• Описание;
• Установка;
• Основные команды;
• Команды для генерации отдельных компонентов;
• Использование;

Описание

Пакет добавляет консольные команды для генерации документации OpenApi в yaml формате

* Пакет работает только с фрейворком Laravel

Установка

1. Установить пакет с помощью менеджера зависимостей composer

   composer require synergyhub/docs-generator:dev-master --dev
   

2. Если не используется auto-discovery, то необходимо зарегистрировать сервис провайдер 'Synergyhub\DocsGenerator\Providers\DocsServiceProvider' в config/app.php

   return [
   //  other configs
    'providers' => [
   //      other providers
        \Synergyhub\DocsGenerator\Providers\DocsServiceProvider::class
    ],
   ];
   

3. Запустить команду для создания конфиг файлов (configs/docs-generator/...)

   $ php artisan vendor:publish --tag=docs-generator:configs
   

4. Заполнить конфиги.
5. Запустить команду для создания директории, в которой будет находиться документация.

   $ php artisan vendor:publish --tag=docs-generator:docs
   

   После выполнения этих шагов будут доступны консольные команды для генерирования документации.

Основные команды

Генерация компонентов для документации по спецификации jsonapi

$ php artisan docs-generate:components

• При запуске команды будет предложено выбрать модель для которой необходимо построить документацию.
• Для корректной работы необходимо заполнить настройки для модели в файле config/docs-generator/entity-settings.php

Генерация компонентов для документации для сущностей для которых есть конфиги в файле configs/docs-generator/entity-settings.php

$ php artisan docs-generate:components --all

Генерация маршрутов для сущностей у которых описаны конфиги в файле configs/docs-generator/entity-settings.php

$ php artisan docs-generate:path --all

Сборка документации в файл .../src/openapi.yaml

$ php artisan docs-generate:build

Команды для генерации отдельных компонентов

Генерация компонентов parameters для openapi документации

$ php artisan docs-generate:params

Генерация компонентов request-body для openapi документации

$ php artisan docs-generate:request

Генерация компонентов request для openapi документации

$ php artisan docs-generate:response

Генерация компонентов schema для openapi документации

$ php artisan docs-generate:schema

Использование

1. Необходимо установить пакет в проект
2. Заполнить конфигурационный файл (entity-settings.php)
3. Выполнить команды:

   $ php artisan docs-generate:components --all
   

   $ php artisan docs-generate:path --all
   

   $ php artisan docs-generate:build
   

4. После этого необходимо создать два маршрута:
   1. Для файла документации
   2. Для отображения графического интерфейса документации

Пример:

$configs = config('docs-generator.settings');

Route::get($configs['docs_url'], function () use ($configs) {
    return view('redoc.spec');
})->name('docs-generator.spec');

Route::get($configs['document_url'], function () use ($configs) {
    return File::get(sprintf('%s/openapi.yaml', $configs['docs_path']));
})->name('docs-generator.spec.document');```

После этого можно открыть документацию в браузере
по пути: https://{ваш_домен}/{путь_который_вы_укзали_в_settings.php}

Пример: https://example.ru/api/v1/docs/spec