概要

急遽、Qiitaアドベントカレンダーの記事を追記で書くことになりました。
ネタを探していたところ、前々からLaravelにSwaggerを取り入れてAPI設計書を作る手順を備忘録的に残しておきたいことを思い出したので、それを書くことにしました。
ソフトウェア開発を中心に携わっていた時はよく使っていましたが、インフラ中心になった今は見ることも無くなったので、思い出しながら書いていきます。
これからSwaggerを使っていく人の参考になればと思います。

Swaggerとは

SwaggerとはAPI設計のツールセットやフレームワークの総称とのこと。私は「Swagger」と言いますが、調べていくと大体「OpenAPI」という名称も出てきて、「今はSwaggerって言わないで、OpenAPIというのかな？」と思っていました。
OpenAPIとは統一された仕様のことであり、Swaggerはツール。ツールにはPostmanやRedocがあるとのこと。
まぁPostmanは有名ですよね〜ただ、あまり使ったことがないな〜API Testerを中心で使っているので、いつかちゃんと使ってみよう。

Swaggerのメリット

色々とメリットがありますが、チーム間で一貫性のあるAPI設計できることが一番メリットかなと思います。
バックエンド側の構築を待たずにSwaggerで作ったAPI設計をもとにフロントエンド側が作業できて、チーム開発のボトルネックを減らせるのが良いですね。
まぁ、他にもメリットは多いですが、使いながら享受してください。

Swaggerのデメリット

これはSwaggerというかLaravelで使うSwaggerなんですが、コーディングの仕方を覚えるのが大変というところです。アノテーションとして記述するのですが、絶妙に表現したいことができなくて悶々とすることがあります。
まぁ調べたら大抵できますが、できないところは仕方がないかなと。私は確か連想配列の中の配列を表現する方法を探した記憶がありますね〜メリットの方が大きいので、デメリットは気合いで解決してください。

構築

前提

macOS
OrbStack
Laravel 11（sailを使用）
Laravelでアプリ作成できるまでの設定は終わっていること

Laravelの導入

Sailを使ってサクッとLaravelを導入。

curl -s https://laravel.build/sample | bash
cd sample
./vendor/bin/sail artisan migrate
./vendor/bin/sail up -d

Swagger-phpの導入

Swagder生成ライブラリSwagger-phpを導入します。

./vendor/bin/sail composer require zircote/swagger-php

l5-generateの導入

APIドキュメントの生成ライブラリl5-generateを導入します。

./vendor/bin/sail composer require "darkaonline/l5-swagger"
./vendor/bin/sail artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

基本設定を記載

/sample/app/Http/Controllers/Controller.phpにAPIドキュメントを生成するための基本設定をControllerに記載します。

<?php

namespace App\Http\Controllers;
use OpenApi\Attributes as OA;

/**
 * @OA\Info(
 *     version="1.0.0",
 *     title="Test API Document",
 *     description="Test API Document"
 * )
 *
 * @OA\Server(
 *     url="http:localhost/api",
 *     description="Local server"
 * )
 */
abstract class Controller
{
    //
}

基本設定ですので、内容はなんとなく分かるかなと。

APIエンドポイントの定義を記載

まずはサンプルのコントローラーを作ります。

./vendor/bin/sail artisan make:controller SampleController --api

次に/sample/app/Http/Controllers/SampleController.phpにAPIエンドポイントの定義を記載していきます。
一旦、indexメソッドに。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class SampleController extends Controller
{
    /**
     * Display a listing of the resource.
     */

    /**
     * @OA\Get(
     *     path="/sample",
     *     summary="get sample index",
     *     description="get list samples for test",
     *     @OA\Response(response=200, description="sucucess get sapmle index")
     * )
     */
    public function index()
    {
        //
    }

Getメソッドのリクエストを/sampleパスに投げて、200番の成功が返ってくるという何の変哲もない定義です。

ドキュメント生成コマンドを叩く

Swaggerドキュメント生成するので下記コマンドを叩いてください。

./vendor/bin/sail artisan l5-swagger:generate

次に下記のurlをブラウザで確認してみましょう。

http://localhost/api/documentation

そうすると、

こんな感じにSwaggerで作成したのOpenAPIの定義書が表示されます。

最後に

LaravelでSwaggerを使ってAPI定義書を作ってみました。
本来はPostやUpdateメソッドを使って、リクエストBodyやレスポンスBody、エラーなどの定義をしていきますが、それはまた別の機会に書いていきます。まずは手始めに導入ができれば良いかなと思います。

なんか、最近、Laravel界隈が燃えていましたが、私はサクッと作る時はLaravel好きですよ〜使い慣れているということもありますが。しっかりと作りたいときは、.Netですかね〜Spring Bootのプロジェクトは1回しかしたことがない。

一旦、こんな感じですので、何かご指摘等ありましたら、コメント頂ければありがたので、よろしくお願いいたします