Докладний посібник зі створення документації для API-відповідей за допомогою Scramble

Документування відповідей API може бути одним із найскладніших етапів при створенні API в Laravel. Це відбувається через просте оновлення документації, яке стає проблемою зі зростанням проєкту.

Ось кілька основних викликів при документуванні відповідей API:

• забезпечення точності
• синхронізація документації з розвитком проєкту

Scramble — це сучасний генератор документації API для Laravel, який вирішує ці проблеми. Замість того, щоб покладатися на ручні анотації, він використовує статичний аналіз коду для створення точної документації відповідей API, яка завжди буде актуальною.

У цій статті ми зосередимося на документуванні відповідей API. Якщо вас цікавить, як документувати API-запити, ознайомтеся з моєю попередньою статтею.

# Мінімізація ручної праці

Основна мета Scramble — автоматично генерувати якомога більше документації API, без потреби писати ручні анотації. Це дозволяє отримати точну документацію у відповідях, яка завжди відповідає проєкту.

Scramble аналізує методи контролерів для визначення типів повернення, на основі яких документує відповіді API, значно скорочуючи потребу в ручному зазначенні того, що вже зрозуміло з коду.

Ось кілька поширених прикладів.

# Ресурси API

Звичайний підхід полягає в поверненні ресурсу API під час створення, отримання або оновлення моделі:

Аналізуючи цей код, Scramble визначає, що відповідь цього методу буде екземпляром CampaignResource. Потім, аналізуючи метод CampaignResource@toArray, Scramble створює схему для CampaignResource, завершуючи документацію для ендпоінта index.

Також Scramble має глибоке розуміння додаткових даних, які ви додаєте до ресурсів або колекцій ресурсів:

У ваших ресурсах ви можете визначити метод with, що також буде задокументовано.

Метод withResponse у класі вашого ресурсу дозволяє налаштувати відповідь, і Scramble збереже цю інформацію в документації.

# Моделі

Моделі та колекції моделей, які повертаються з ваших методів контролерів, також документуються автоматично:

# Колекції ресурсів

Також підтримуються колекції ресурсів.

Наприклад, звичайний спосіб повернення списку пагінованих елементів — обернути пагінатор у колекцію ресурсів:

Зверніть увагу, що вам не потрібно вручну документувати відповідь пагінатора — це працює автоматично ✨

Окрім анонімних колекцій ресурсів, також підтримуються кастомні колекції.

У недавньому випуску Scramble став розумнішим — тепер підтримує кастомні анонімні колекції: коли ви переозначите метод newCollection (або collection) у класі ресурсу, це буде враховано при генерації документації.

# JSON-відповіді

Коли ви повертаєте JSON-відповідь, Scramble також справляється з цим (принаймні, якщо тип даних відповіді можна визначити):

Чарівність аналізу типів для генерації документації API в тому, що, коли ви ланцюжите метод response на ваших ресурсах API, Scramble розуміє, що повертається JSON-відповідь і може належним чином задокументувати будь-які налаштування, які ви застосовуєте:

# Завантаження файлів, потоки JSON-відповідей, події потоків

Коли ви повертаєте відповідь завантаження файлу з ендпоінта, Scramble також це задокументує. Більше того! Якщо у вашій виразі створення відповіді вказано розширення файлу, Scramble передбачить тип вмісту 🤯 Це наче магія!

// app/Models/Campaign.php
public function getPdfReportName(Campaign $campaign): string
{
    return $this->name.'-'.now()->toDateString().'.pdf';
}
 
// app/Http/Controllers/CampaignsController.php
public function downloadPdfReport(Campaign $campaign)
{
    return response()->file($campaign->getPdfReportName());
}

Потокові відповіді також документуються:

public function __invoke()
{
    return response()->stream(function () {
        foreach (['developer', 'admin'] as $string) {
            echo $string;
        }
    }, 200, ['X-Accel-Buffering' => 'no']);
}

А також події потоків:

public function __invoke()
{
    return response()->eventStream(function () {
        // ...
    });
}

# Додавання ручної документації для відповідей за необхідності

Коли Scramble завершить свою роботу і ви отримаєте документацію з вашої кодової бази, ви зможете додати деяку документацію вручну за потреби — описи відповідей, заголовки тощо.

# Додавання документації заголовків вручну

Щоб вручну додати документацію заголовків відповіді для одного з відповідей, ви можете використати атрибут Header:

Якщо вам потрібно додати заголовок відповіді для всіх ваших відповідей, ви можете використати трансформер операцій і додати його там:

Scramble::configure()
    ->withOperationTransformers(function (Operation $operation) {
        foreach ($operation->responses as $response) {
            if (! $response instanceof Response) {
                continue;
            }
            $response->addHeader(
                'X-RateLimit-Limit',
                new Header('Ліміт частоти', schema: Schema::fromType(new IntegerType)),
            );
        }
    });

# Ручне додавання відповіді

Якщо Scramble не розпізнав деякі відповіді, ви завжди можете додати їх вручну.

Використовуючи атрибут Response, ви можете додати документацію відповіді до ендпоінта:

use Dedoc\Scramble\Attributes\Response;
 
#[Response(200, 'Файл експорту Excel', mediaType: 'application/vnd.ms-excel', type: 'string', format: 'binary')]
public function index()
{}

Атрибут Response дозволяє не лише додати нову документацію відповіді, але й удосконалити вже проінферовані відповіді:

use Dedoc\Scramble\Attributes\Response;
 
#[Response(description: 'Запитуваний ресурс кампанії.')]
public function show(Campaign $campaign)
{
    return CampaignResource::make($campaign);
}

# Налаштування статусу відповіді та тіла

Для налаштування статусу відповіді, що випливає з кодової бази, можна використовувати анотацію PHPDoc @status.

Це може бути корисно при документуванні відповідей, що створюють нові моделі. Фактичний статус відповіді завжди буде 201, але Scramble в даний момент задокументує його як 200. Ви можете покращити документацію вручну:

public function store()
{
    /** @status 201 */
    return CampaignResource::make(/* ... */);
}

# Висновок

За допомогою Scramble ви можете отримати точну документацію API з мінімальними зусиллями. Результуюча документація завжди перебуватиме у синхронізації з кодовою базою. За необхідності ви можете додати додаткові деталі вручну.

Ось простий демонстраційний проєкт, який використовує Scramble для документації API, щоб ви могли ознайомитися з його можливостями:

Демонстраційний сайт документації: https://scramble.dedoc.co/demo/scramble#/

Демонстраційний репозиторій документації: https://github.com/dedoc/demo-scramble

Якщо ви працюєте над проєктом API на Laravel, спробуйте Scramble! Завітайте на https://scramble.dedoc.co, щоб дізнатися більше!