README

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

Описание

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

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

Установка

Установить пакет с помощью менеджера зависимостей composer
```
composer require synergyhub/docs-generator:dev-master --dev
```
Если не используется auto-discovery, то необходимо зарегистрировать сервис провайдер 'Synergyhub\DocsGenerator\Providers\DocsServiceProvider' в config/app.php
```
return [
//  other configs
 'providers' => [
//      other providers
     \Synergyhub\DocsGenerator\Providers\DocsServiceProvider::class
 ],
];
```
Запустить команду для создания конфиг файлов (configs/docs-generator/...)
```
$ php artisan vendor:publish --tag=docs-generator:configs
```
Заполнить конфиги.
Запустить команду для создания директории, в которой будет находиться документация.
```
$ 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

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

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

Выполнить команды:

$ php artisan docs-generate:components --all

$ php artisan docs-generate:path --all

$ php artisan docs-generate:build

После этого необходимо создать два маршрута:
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

synergyhub / docs-generator

Maintainers

Details