Автоматизована документація API для ресурсів Laravel

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

Scramble — це автоматичний генератор документації для Laravel, який створює документацію API без необхідності використовувати PHPDoc анотації та має вбудовану підтримку API ресурсів: scramble.dedoc.co.

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

# Використання API ресурсів

Припустимо, ми хочемо повернути модель користувача через API. Ми можемо створити наступний API ресурс:

<?php
namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }
}

У контролері ми повертаємо екземпляр ресурсу, передаючи модель користувача в його конструктор:

public function show(User $user)
{
    return new UserResource($user);
}

Хоча ресурси можуть виглядати простими, вони насправді дуже всеосяжні. Є багато корисних методів для формування представлення моделі у API: деякі дозволяють об'єднувати дані в результатуючий масив (наприклад, merge, mergeWhen), інші, такі як whenLoaded, дозволяють включати відношення лише тоді, коли воно завантажене — це допомагає уникнути проблеми N+1.

# Автоматична документація Scramble

Scramble — це генератор документації OpenAPI (Swagger) для Laravel. Він автоматично створює документацію API для вашого проекту без потреби вручну писати PHPDoc анотації.

Це забезпечує актуальність вашої документації, що дозволяє покладатися на неї з упевненістю.

Встановити Scramble можна через composer:

composer require dedoc/scramble

Після установки Scramble ви можете переглянути документацію для нашого прикладу ендпоінта (передбачається, що він знаходиться за адресою /api/user/{user} і ви не змінили налаштування за замовчуванням):

Без жодних анотацій Scramble вже документує тип відповіді.

Тепер давайте покращимо API ресурс, додавши нові можливості. Наприклад, ми можемо захотіти відображати атрибут email лише тоді, коли автентифікований користувач є адміністратором.

    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
-           'email' => $this->email,
+           $this->mergeWhen($request->user()->is_admin, [
+               /** @format email */
+               'email' => $this->email,
+           ]),
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }

Тепер Scramble документує ресурс таким чином, що правильно вказує, що атрибут email може бути відсутнім у відповіді (зверніть увагу, що email більше не позначається як обов'язковий):

Широкий вибір методів, таких як when, доступні через трейті ConditionallyLoadsAttributes, який використовується в JsonResource. У новій версії Scramble тепер підтримує всі ці методи.

Наприклад, метод attributes дозволяє об'єднати кілька атрибутів моделі в результатуючий масив:

    public function toArray(Request $request): array
    {
        return [
-           'id' => $this->id,
-           'name' => $this->name,
+           $this->attributes(['id', 'name']),
            $this->mergeWhen($request->user()->is_admin, [
                /** @format email */
                'email' => $this->email,
            ]),
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }

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

Ви також можете повертати колекції API ресурсів з вашого API. Наприклад, коли повертаєте список користувачів, ви можете реалізувати це так:

public function index()
{
    return UserResource::collection(User::all());
}

# Документування колекцій ресурсів

Scramble підтримує анонімні та іменовані колекції з коробки.

Ось згенерована документація для наведеного вище прикладу:

Якщо ви додасте додаткові дані до колекції, Scramble автоматично задокументує це:

public function index()
{
    return UserResource::collection($users = User::all())->additional([
        /** Загальна кількість користувачів */
        'count' => (int) $users->count(),
    ]);
}

Ось результуюча документація:

# Модифікація відповіді ресурсу

Ще одна чудова функція API ресурсів — це можливість змінювати відповідь, яка повертається з API ендпоінта. Це реалізується через модифікацію об'єкта відповіді в методі withResponse в API ресурсі:

public function withResponse(Request $request, JsonResponse $response)
{
    $response->setStatusCode(201);
}

# Задокументований модифікований ресурс

Scramble підтримує документацію для withResponse без додаткових анотацій. Приклад з вище буде задокументовано наступним чином:

Зверніть увагу, що статус відповіді 201, як зазначено в статусі withResponse.

API ресурси є безцінним інструментом для розробників на Laravel. Вони дозволяють готувати моделі для API-відповідей з використанням потужного рівня трансформації.

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

Якщо ви ще не використовуєте Scramble, спробуйте його: https://scramble.dedoc.co

Ось демонстраційна документація від Scramble: https://scramble.dedoc.co/demo/scramble