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
2. Copyright © M&A Cloud All rights reserved. 自己紹介 株式会社M＆Aクラウド 塚原 彰仁 　　 AkitoTsukahara AkitoTsukahara 近況：先月転職しました！ 2
3. 3 事業売却と資金調達で次のステージへ
 業界初の買い手の顔が見えるM&Aプラットフォーム

4. Copyright © M&A Cloud All rights reserved. 突然ですが・・・ 突然ですが・・・ APIドキュメント用意するのって、 大変じゃないですか？ 4
5. Copyright © M&A Cloud All rights reserved. 大変なんだよ、これが・・・ ・そもそもAPIドキュメント書いている時間ない ・ある時期からドキュメントが更新されていない ・先にドキュメントしたらと、 　まずは動くものが欲しいと言われる 5 大変なんだよ、これが・・・
6. Copyright © M&A Cloud All rights reserved. Swaggerを使ってみたお話です 6 このLTは解決策の１つとして、 Swaggerを使ってみたお話です
7. Copyright © M&A Cloud All rights reserved. Swaggerとは？ SwaggerとはRESTful APIのドキュメントや、サーバ、クライアントコード、エ ディタ、またそれらを扱うための仕様などを提供するフレームワークです。 （引用：Qiita） 7 Swaggerとは？
8. Copyright © M&A Cloud All rights reserved. こんな感じになります 8 swagger UIの図を載せる 元のコードの図を載せる コードからドキュメントができる
9. Copyright © M&A Cloud All rights reserved. Swaggerとは？ 9 お！良さげなのでは？
10. Copyright © M&A Cloud All rights reserved. このLTで話すこと・話さないこと 10 このLTで話すこと・話さないこと 話すこと ・Swagger導入で解決できること ・導入してみて感じたこと 話さないこと ・REST APIの実装方法 ・Swagger導入に必要な設定方法 →この辺りの話はQiitaで記事にしておきました！
11. Copyright © M&A Cloud All rights reserved. ざっくり解説の前に 11 ざっくり解説の前に ・紹介するサンプルは CakePHP4で作られています ・サンプル中のREST APIはCakePHPクックブックを参考にしています ・Dockerでの動作確認ができる状態を目指してます ・サンプルのコードは以下で公開中 　https://github.com/AkitoTsukahara/swagger-cakephp
12. Copyright © M&A Cloud All rights reserved. できるようになること 12 できるようになること 1.コードからドキュメント生成 2.クライアント化 3.モックサーバー
13. Copyright © M&A Cloud All rights reserved. ドキュメントができる流れ 13 ドキュメントができる流れ swagger-php swagger-ui コード中のアノテー ションからJSONを生 成 JSONファイルを ドキュメントに変換 code JSON document
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
15. Copyright © M&A Cloud All rights reserved. <?php 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
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
17. Copyright © M&A Cloud All rights reserved. Swagger UIを開いてみると 17 swagger UIの図を載せる 元のコードの図を載せる Swagger UIを開いてみると
18. Copyright © M&A Cloud All rights reserved. クライアント化 Swagger UIを利用するとドキュメントに 合わせたパラメータでリクエストを送信して結果を 確認することができます。 18 クライアント化
19. Copyright © M&A Cloud All rights reserved. モックサーバー Swagger Editorを利用するとドキュメント同じJSONを 返すモックサーバーを作成できます。 
 
 プロトタイプ時でサーバー実装が完了していない場 合でも、モックサーバーがあればフロントエンドも同 時開発可能になります。 
 19 モックサーバー
20. Copyright © M&A Cloud All rights reserved. 生成したモックサーバーを　　　　　　することで、利用できる様になります。 Swagger Editor からモックサーバーを生成 20 Swagger Editor からモックサーバーを生成 yarn start
21. Copyright © M&A Cloud All rights reserved. Swagger Editorのイメージ映像 21
22. Copyright © M&A Cloud All rights reserved. 社内で共有したところ 22 社内で共有してみたところ コード中にドキュメントがあるから、 変更時のドキュメント更新を忘れなくなりそう 実際に動かして、リクエストと レスポンス内容を確認できるのが便利！
23. Copyright © M&A Cloud All rights reserved. こんな声もありました 23 アノテーション書くの大変じゃない...？
24. Copyright © M&A Cloud All rights reserved. この言葉が出てきたらむしろ成功 この言葉が出てきたらむしろ成功
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
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を使い、 　共通化したオブジェクトを呼び出す
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
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
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種
30. Copyright © M&A Cloud All rights reserved. まとめ ・コードからドキュメントを生成できる開発体験は素敵でした！ ・先にドキュメントを用意しておけば、 　フロントエンドと同時進行で開発できるのも素敵！ ・運用ルールはチームで話し合いながら、決めていくのが良さそう ・最初は大変だけど、慣れれば簡単だよ 30 使ってみた感想
31. Copyright © M&A Cloud All rights reserved. 細かい部分はこっちを見てね！ Swagger導入をまとめた記事 今回のLTで紹介した実装方法の詳細記事 Web API開発をするなら、ドキュメントは自動生成にしておこう！（CakePHP編） 参考にさせていただいた記事 APIドキュメントを支える技術 CakePHP4 で Swagger3 を使って API ドキュメントを作る OpenAPI (Swagger) の基本的なあれこれ 31
32. Copyright © M&A Cloud All rights reserved. ありがとうございました！ 32