Web API開発をするなら、ドキュメントは自動生成にしておこう！（PHPerKaigi2021）

皆さんの開発現場はAPIドキュメントの自動生成化がお済みでしょうか？
このLTではCakePHP4にSwaggerを導入して、コードのアノテーションからドキュメントを自動生成するまでの流れをご紹介いたします。

▼こんな方におすすめ
・これからWeb API開発を始める方
・ドキュメント書くの面倒な方
・実装とドキュメントの乖離に苦労したことがある方

昨年、社内で実施した勉強会のテーマの中で一番メンバーの反応が良かったのが「アノテーションからのドキュメント自動生成」でした。ドキュメント作成の手間を少しでも減らして、開発体験を向上させていきましょう！
（LTではCakePHPをサンプルコードとして紹介いたしますが、Laravelに導入する手順も別途資料をご用意させていただく予定です。）
https://fortee.jp/phperkaigi-2021/proposal/976b1869-082b-4309-a2c5-f23ae43bd134

Transcript

1. Copyright © M&A Cloud All rights reserved.
   PHPerKaigi2021 / LT
   Akito Tsukahara
   Web API開発をするなら、
   ドキュメントは自動生成にしておこう！
   1
   

   View Slide

2. Copyright © M&A Cloud All rights reserved.
   自己紹介
   株式会社M＆Aクラウド
   塚原 彰仁
   　　 AkitoTsukahara
   AkitoTsukahara
   近況：先月転職しました！
   2
   

   View Slide

3. 3
   事業売却と資金調達で次のステージへ

   業界初の買い手の顔が見えるM&Aプラットフォーム

   

   View Slide

4. Copyright © M&A Cloud All rights reserved.
   突然ですが・・・
   突然ですが・・・
   APIドキュメント用意するのって、
   大変じゃないですか？
   4
   

   View Slide

5. Copyright © M&A Cloud All rights reserved.
   大変なんだよ、これが・・・
   ・そもそもAPIドキュメント書いている時間ない
   ・ある時期からドキュメントが更新されていない
   ・先にドキュメントしたらと、
   　まずは動くものが欲しいと言われる
   5
   大変なんだよ、これが・・・
   

   View Slide

6. Copyright © M&A Cloud All rights reserved.
   Swaggerを使ってみたお話です
   6
   このLTは解決策の１つとして、
   Swaggerを使ってみたお話です
   

   View Slide

7. Copyright © M&A Cloud All rights reserved.
   Swaggerとは？
   SwaggerとはRESTful APIのドキュメントや、サーバ、クライアントコード、エ
   ディタ、またそれらを扱うための仕様などを提供するフレームワークです。
   （引用：Qiita）
   7
   Swaggerとは？
   

   View Slide

8. Copyright © M&A Cloud All rights reserved.
   こんな感じになります
   8
   swagger UIの図を載せる
   元のコードの図を載せる
   コードからドキュメントができる
   

   View Slide

9. Copyright © M&A Cloud All rights reserved.
   Swaggerとは？
   9
   お！良さげなのでは？
   

   View Slide

10. Copyright © M&A Cloud All rights reserved.
    このLTで話すこと・話さないこと
    10
    このLTで話すこと・話さないこと
    話すこと
    ・Swagger導入で解決できること
    ・導入してみて感じたこと
    話さないこと
    ・REST APIの実装方法
    ・Swagger導入に必要な設定方法
    →この辺りの話はQiitaで記事にしておきました！
    

    View Slide

11. Copyright © M&A Cloud All rights reserved.
    ざっくり解説の前に
    11
    ざっくり解説の前に
    ・紹介するサンプルは CakePHP4で作られています
    ・サンプル中のREST APIはCakePHPクックブックを参考にしています
    ・Dockerでの動作確認ができる状態を目指してます
    ・サンプルのコードは以下で公開中
    　https://github.com/AkitoTsukahara/swagger-cakephp
    

    View Slide

12. Copyright © M&A Cloud All rights reserved.
    できるようになること
    12
    できるようになること
    1.コードからドキュメント生成
    2.クライアント化
    3.モックサーバー
    

    View Slide

13. Copyright © M&A Cloud All rights reserved.
    ドキュメントができる流れ
    13
    ドキュメントができる流れ
    swagger-php swagger-ui
    コード中のアノテー
    ションからJSONを生
    成
    JSONファイルを
    ドキュメントに変換
    code JSON document
    

    View Slide

14. Copyright © M&A Cloud All rights reserved.
    composer require --dev zircote/swagger-php
    導入手順１
    scriptにコマンドを登録しておくと、開発中の実行が楽になるのでおすすめ！
    14
    Swaggerのインストール
    Composer scriptsにコマンドを追加
    console
    composer.json
    "openapi": "openapi --output openapi.json --format y src/Controller/Api/"
    composer.json
    

    View Slide

15. Copyright © M&A Cloud All rights reserved.
    declare(strict_types=1);
    /**
    * @OA\Info(
    * title="CakePHP Swagger",
    * description="CakePHP Swagger LT API
    Automatically generate documental",
    * version="1.0.0",
    * )
    */
    /**
    * @OA\Server(
    * description="localhost",
    * url="http://localhost"
    * )
    */
    導入手順２
    15
    共通ドキュメント APIドキュメント
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    /**
    * Index method
    *
    * @OA\Get(
    * path="/api/recipe/index.json",
    * tags={"Recipe"},
    * summary="レシピをすべて取得する
    ",
    * @OA\Response(
    * response=200,
    * description="OK",
    * @OA\JsonContent(
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    /src/Controller/Api/swagger.php（共通化パーツはここ） src/Controller/Api/RecipeController.php
    参考
    CakePHP 4.x Strawberry Cookbook REST
    

    View Slide

16. Copyright © M&A Cloud All rights reserved.
    swagger-ui:
    image: swaggerapi/swagger-ui
    container_name: swagger_cakephp-ui
    ports:
    - 8002:8080
    volumes:
    - ./server:/tmp
    environment:
    SWAGGER_JSON: /tmp/openapi.json
    composer openapi
    導入手順３
    16
    ドキュメントの作成
    Swagger UIのDockerイメージを追加
    console
    docker-compose.yml
    

    View Slide

17. Copyright © M&A Cloud All rights reserved.
    Swagger UIを開いてみると
    17
    swagger UIの図を載せる
    元のコードの図を載せる
    Swagger UIを開いてみると
    

    View Slide

18. Copyright © M&A Cloud All rights reserved.
    クライアント化
    Swagger UIを利用するとドキュメントに
    合わせたパラメータでリクエストを送信して結果を
    確認することができます。
    18
    クライアント化
    

    View Slide

19. Copyright © M&A Cloud All rights reserved.
    モックサーバー
    Swagger Editorを利用するとドキュメント同じJSONを
    返すモックサーバーを作成できます。 

    

    プロトタイプ時でサーバー実装が完了していない場
    合でも、モックサーバーがあればフロントエンドも同
    時開発可能になります。 

    19
    モックサーバー
    

    View Slide

20. Copyright © M&A Cloud All rights reserved.
    生成したモックサーバーを　　　　　　することで、利用できる様になります。
    Swagger Editor からモックサーバーを生成
    20
    Swagger Editor からモックサーバーを生成
    yarn start
    

    View Slide

21. Copyright © M&A Cloud All rights reserved.
    Swagger Editorのイメージ映像
    21
    

    View Slide

22. Copyright © M&A Cloud All rights reserved.
    社内で共有したところ
    22
    社内で共有してみたところ
    コード中にドキュメントがあるから、
    変更時のドキュメント更新を忘れなくなりそう
    実際に動かして、リクエストと
    レスポンス内容を確認できるのが便利！
    

    View Slide

23. Copyright © M&A Cloud All rights reserved.
    こんな声もありました
    23
    アノテーション書くの大変じゃない...？
    

    View Slide

24. Copyright © M&A Cloud All rights reserved.
    この言葉が出てきたらむしろ成功
    この言葉が出てきたらむしろ成功
    

    View Slide

25. Copyright © M&A Cloud All rights reserved.
    一番少ない設定ならこれだけ！完璧な状態からのギャップを
    25
    一番少ない設定ならこれだけ！完璧な状態からのギャップを
    /**
    * @OA\Info(
    * title="CakePHP Swagger",
    * version="1.0.0",
    * )
    */
    /**
    * view method
    *
    * @OA\Get(
    * path="/api/recipe/view/{id}.json",
    * tags={“Recipe”}
    * @OA\Parameter(
    * name="id",
    * in="path",
    * required=true,
    * @OA\Schema(type="string"),
    * ),
    * @OA\Response(
    * response=200,
    * description="OK"
    * ),
    * )
    /src/Controller/Api/swagger.php
    src/Controller/Api/RecipeController.php
    最低限必要な項目
    ・info
    　・title
    　・version
    ・paths
    　・parameter
    　・response
    

    View Slide

26. Copyright © M&A Cloud All rights reserved.
    同じスキーマは共通化する
    26
    同じスキーマは共通化する
    * @OA\Property(
    * property="id",
    * type="string",
    * description="レシピID",
    * ),
    * @OA\Property(
    * property="title",
    * type="string",
    * description="レシピ名",
    * ),
    * @OA\Property(
    * property="description",
    * type="string",
    * description="レシピ内容",
    * ),
    src/Controller/Api/RecipeController.php
    ・共通化したいしたいスキーマオブジェクトを　
    　
    　共通ファイルに定義する
    ・呼び出したい箇所で
    $refを使い、
    　共通化したオブジェクトを呼び出す
    

    View Slide

27. Copyright © M&A Cloud All rights reserved.
    同じスキーマは共通化する
    * @OA\Schema(
    * schema="recipe_object",
    * type="object",
    * @OA\Property(
    * property="id",
    * type="string",
    * description="レシピID",
    * ),
    * @OA\Property(
    * property="title",
    * type="string",
    * description="レシピ名",
    * ),
    * @OA\Property(
    * property="description",
    * type="string",
    * description="レシピ内容",
    * )
    * )
    */ 27
    例１）レスポンスのオブジェクト
    /src/Controller/Api/swagger.php
    / **
    * @OA\Response(
    * type="object",
    * @OA\JsonContent(
    ref="#/components/schemas/recipe_object")
    * ),
    * ),
    src/Controller/Api/RecipeController.php
    

    View Slide

28. Copyright © M&A Cloud All rights reserved.
    同じスキーマは共通化する
    28
    例２）エラーレスポンス
    / **
    * @OA\Schema(
    * schema="default_error_response_content",
    * type="object",
    * @OA\Property(
    * property="message",
    * type="string",
    * description="エラーメッセージ",
    * ),
    * example={
    * "message"="予期しないエラーです
    "
    * },
    * )
    */
    /src/Controller/Api/swagger.php
    / **
    * @OA\Response(
    * response="default",
    * description="Unexpected Error",
    * @OA\JsonContent(
    ref="#/components/schemas/
    default_error_response_content")
    * ),
    * ),
    src/Controller/Api/RecipeController.php
    

    View Slide

29. Copyright © M&A Cloud All rights reserved.
    コピペ用のデフォルトアノテーションを用意する
    29
    コピペ用のデフォルトアノテーションを用意しておく
    @OA\Response(response=200, description="OK")
    @OA\Response(response=201, description="Created")
    @OA\Response(response=202, description="Accepted")
    @OA\Response(response=204, description="No Content")
    @OA\Response(response=207, description="Multi-Status")
    @OA\Response(response=304, description="Not Modified")
    @OA\Response(response=400, description="Bad Request")
    @OA\Response(response=401, description="Unauthorized")
    @OA\Response(response=403, description="Forbidden")
    @OA\Response(response=405, description="Method Not Allowed")
    @OA\Response(response=500, description="Internal Server Error")
    @OA\Response(response=503, description="Service Unavailable")
    レスポンス一覧
    こちらも参考に
    swagger-php で書く Annotation テンプレ3種
    

    View Slide

30. Copyright © M&A Cloud All rights reserved.
    まとめ
    ・コードからドキュメントを生成できる開発体験は素敵でした！
    ・先にドキュメントを用意しておけば、
    　フロントエンドと同時進行で開発できるのも素敵！
    ・運用ルールはチームで話し合いながら、決めていくのが良さそう
    ・最初は大変だけど、慣れれば簡単だよ
    30
    使ってみた感想
    

    View Slide

31. Copyright © M&A Cloud All rights reserved.
    細かい部分はこっちを見てね！
    Swagger導入をまとめた記事
    今回のLTで紹介した実装方法の詳細記事
    Web API開発をするなら、ドキュメントは自動生成にしておこう！（CakePHP編）
    参考にさせていただいた記事
    APIドキュメントを支える技術
    CakePHP4 で Swagger3 を使って API ドキュメントを作る
    OpenAPI (Swagger) の基本的なあれこれ
    31
    

    View Slide

32. Copyright © M&A Cloud All rights reserved.
    ありがとうございました！
    32
    

    View Slide