Share
Embed
Web API開発をするなら、ドキュメントは自動生成にしておこう!(PHPerKaigi2021)
皆さんの開発現場はAPIドキュメントの自動生成化がお済みでしょうか?
このLTではCakePHP4にSwaggerを導入して、コードのアノテーションからドキュメントを自動生成するまでの流れをご紹介いたします。
▼こんな方におすすめ
・これからWeb API開発を始める方
・ドキュメント書くの面倒な方
・実装とドキュメントの乖離に苦労したことがある方
昨年、社内で実施した勉強会のテーマの中で一番メンバーの反応が良かったのが「アノテーションからのドキュメント自動生成」でした。ドキュメント作成の手間を少しでも減らして、開発体験を向上させていきましょう!
(LTではCakePHPをサンプルコードとして紹介いたしますが、Laravelに導入する手順も別途資料をご用意させていただく予定です。)
https://fortee.jp/phperkaigi-2021/proposal/976b1869-082b-4309-a2c5-f23ae43bd134
AkitoTsukahara
March 15, 2021
Transcript
32 slides
-
Copyright © M&A Cloud All rights reserved. PHPerKaigi2021 / LT
Akito Tsukahara Web API開発をするなら、 ドキュメントは自動生成にしておこう! 1 -
Copyright © M&A Cloud All rights reserved. 自己紹介 株式会社M&Aクラウド 塚原
彰仁 AkitoTsukahara AkitoTsukahara 近況:先月転職しました! 2 -
Copyright © M&A Cloud All rights reserved. 大変なんだよ、これが・・・ ・そもそもAPIドキュメント書いている時間ない ・ある時期からドキュメントが更新されていない
・先にドキュメントしたらと、 まずは動くものが欲しいと言われる 5 大変なんだよ、これが・・・ -
Copyright © M&A Cloud All rights reserved. Swaggerとは? SwaggerとはRESTful APIのドキュメントや、サーバ、クライアントコード、エ
ディタ、またそれらを扱うための仕様などを提供するフレームワークです。 (引用:Qiita) 7 Swaggerとは? -
Copyright © M&A Cloud All rights reserved. こんな感じになります 8 swagger
UIの図を載せる 元のコードの図を載せる コードからドキュメントができる -
Copyright © M&A Cloud All rights reserved. このLTで話すこと・話さないこと 10 このLTで話すこと・話さないこと
話すこと ・Swagger導入で解決できること ・導入してみて感じたこと 話さないこと ・REST APIの実装方法 ・Swagger導入に必要な設定方法 →この辺りの話はQiitaで記事にしておきました! -
Copyright © M&A Cloud All rights reserved. ざっくり解説の前に 11 ざっくり解説の前に
・紹介するサンプルは CakePHP4で作られています ・サンプル中のREST APIはCakePHPクックブックを参考にしています ・Dockerでの動作確認ができる状態を目指してます ・サンプルのコードは以下で公開中 https://github.com/AkitoTsukahara/swagger-cakephp -
Copyright © M&A Cloud All rights reserved. できるようになること 12 できるようになること
1.コードからドキュメント生成 2.クライアント化 3.モックサーバー -
Copyright © M&A Cloud All rights reserved. ドキュメントができる流れ 13 ドキュメントができる流れ
swagger-php swagger-ui コード中のアノテー ションからJSONを生 成 JSONファイルを ドキュメントに変換 code JSON document -
Copyright © M&A Cloud All rights reserved. composer require --dev
zircote/swagger-php 導入手順1 scriptにコマンドを登録しておくと、開発中の実行が楽になるのでおすすめ! 14 Swaggerのインストール Composer scriptsにコマンドを追加 console composer.json "openapi": "openapi --output openapi.json --format y src/Controller/Api/" composer.json -
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" * ) */ 導入手順2 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 -
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 導入手順3 16 ドキュメントの作成 Swagger UIのDockerイメージを追加 console docker-compose.yml -
Copyright © M&A Cloud All rights reserved. Swagger UIを開いてみると 17
swagger UIの図を載せる 元のコードの図を載せる Swagger UIを開いてみると -
Copyright © M&A Cloud All rights reserved. クライアント化 Swagger UIを利用するとドキュメントに
合わせたパラメータでリクエストを送信して結果を 確認することができます。 18 クライアント化 -
Copyright © M&A Cloud All rights reserved. モックサーバー Swagger Editorを利用するとドキュメント同じJSONを
返すモックサーバーを作成できます。 プロトタイプ時でサーバー実装が完了していない場 合でも、モックサーバーがあればフロントエンドも同 時開発可能になります。 19 モックサーバー -
Copyright © M&A Cloud All rights reserved. 生成したモックサーバーを することで、利用できる様になります。 Swagger Editor
からモックサーバーを生成 20 Swagger Editor からモックサーバーを生成 yarn start -
Copyright © M&A Cloud All rights reserved. 社内で共有したところ 22 社内で共有してみたところ
コード中にドキュメントがあるから、 変更時のドキュメント更新を忘れなくなりそう 実際に動かして、リクエストと レスポンス内容を確認できるのが便利! -
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 -
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を使い、 共通化したオブジェクトを呼び出す -
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 例1)レスポンスのオブジェクト /src/Controller/Api/swagger.php / ** * @OA\Response( * type="object", * @OA\JsonContent( ref="#/components/schemas/recipe_object") * ), * ), src/Controller/Api/RecipeController.php -
Copyright © M&A Cloud All rights reserved. 同じスキーマは共通化する 28 例2)エラーレスポンス
/ ** * @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 -
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種 -
Copyright © M&A Cloud All rights reserved. まとめ ・コードからドキュメントを生成できる開発体験は素敵でした! ・先にドキュメントを用意しておけば、
フロントエンドと同時進行で開発できるのも素敵! ・運用ルールはチームで話し合いながら、決めていくのが良さそう ・最初は大変だけど、慣れれば簡単だよ 30 使ってみた感想 -
Copyright © M&A Cloud All rights reserved. 細かい部分はこっちを見てね! Swagger導入をまとめた記事 今回のLTで紹介した実装方法の詳細記事
Web API開発をするなら、ドキュメントは自動生成にしておこう!(CakePHP編) 参考にさせていただいた記事 APIドキュメントを支える技術 CakePHP4 で Swagger3 を使って API ドキュメントを作る OpenAPI (Swagger) の基本的なあれこれ 31