Web api開発をするならドキュメントは自動生成にしておこう__ph_per_kaigi2021_

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

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

3
事業売却と資金調達で次のステージへ 
業界初の買い手の顔が見えるM&Aプラットフォーム

突然ですが・・・
突然ですが・・・
APIドキュメント用意するのって、
大変じゃないですか？
4

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

Swaggerを使ってみたお話です
6
このLTは解決策の１つとして、
Swaggerを使ってみたお話です

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

こんな感じになります
8
swagger UIの図を載せる
元のコードの図を載せる
コードからドキュメントができる

Swaggerとは？
9
お！良さげなのでは？

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

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

できるようになること
12
できるようになること
1.コードからドキュメント生成
2.クライアント化
3.モックサーバー

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

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

<?php
declare(strict_types=1);
/**
* @OAInfo(
* title="CakePHP Swagger",
* description="CakePHP Swagger LT API
Automatically generate documental",
* version="1.0.0",
* )
*/
/**
* @OAServer(
* description="localhost",
* url="http://localhost"
* )
*/
導入手順２
15
共通ドキュメント APIドキュメント
~~~~~~~~~~~~~~~~~~~~~~~~~~~
/**
* Index method
*
* @OAGet(
* path="/api/recipe/index.json",
* tags={"Recipe"},
* summary="レシピをすべて取得する
",
* @OAResponse(
* response=200,
* description="OK",
* @OAJsonContent(
~~~~~~~~~~~~~~~~~~~~~~~~~~~
/src/Controller/Api/swagger.php（共通化パーツはここ） src/Controller/Api/RecipeController.php
参考
CakePHP 4.x Strawberry Cookbook REST

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

Swagger UIを開いてみると
17
swagger UIの図を載せる
元のコードの図を載せる
Swagger UIを開いてみると

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

モックサーバー
Swagger Editorを利用するとドキュメント同じJSONを
返すモックサーバーを作成できます。  
 
プロトタイプ時でサーバー実装が完了していない場
合でも、モックサーバーがあればフロントエンドも同
時開発可能になります。  
19
モックサーバー

生成したモックサーバーを　　　　　　することで、利用できる様になります。
Swagger Editor からモックサーバーを生成
20
Swagger Editor からモックサーバーを生成
yarn start

Swagger Editorのイメージ映像
21

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

こんな声もありました
23
アノテーション書くの大変じゃない...？

この言葉が出てきたらむしろ成功
この言葉が出てきたらむしろ成功

一番少ない設定ならこれだけ！完璧な状態からのギャップを
25
一番少ない設定ならこれだけ！完璧な状態からのギャップを
/**
* @OAInfo(
* title="CakePHP Swagger",
* version="1.0.0",
* )
*/
/**
* view method
*
* @OAGet(
* path="/api/recipe/view/{id}.json",
* tags={“Recipe”}
* @OAParameter(
* name="id",
* in="path",
* required=true,
* @OASchema(type="string"),
* ),
* @OAResponse(
* response=200,
* description="OK"
* ),
* )
/src/Controller/Api/swagger.php
src/Controller/Api/RecipeController.php
最低限必要な項目
・info
　・title
　・version
・paths
　・parameter
　・response

同じスキーマは共通化する
26
* @OAProperty(
* property="id",
* type="string",
* description="レシピID",
* ),
* @OAProperty(
* property="title",
* type="string",
* description="レシピ名",
* ),
* @OAProperty(
* property="description",
* type="string",
* description="レシピ内容",
* ),
・共通化したいしたいスキーマオブジェクトを　
　
　共通ファイルに定義する
・呼び出したい箇所で
$refを使い、
　共通化したオブジェクトを呼び出す

* @OASchema(
* schema="recipe_object",
* type="object",
* @OAProperty(
* property="id",
* type="string",
* description="レシピID",
* ),
* @OAProperty(
* property="title",
* type="string",
* description="レシピ名",
* ),
* @OAProperty(
* property="description",
* type="string",
* description="レシピ内容",
* )
* )
*/ 27
例１）レスポンスのオブジェクト
/ **
* @OAResponse(
* type="object",
* @OAJsonContent(
ref="#/components/schemas/recipe_object")
* ),
* ),

28
例２）エラーレスポンス
/ **
* @OASchema(
* schema="default_error_response_content",
* type="object",
* @OAProperty(
* property="message",
* type="string",
* description="エラーメッセージ",
* ),
* example={
* "message"="予期しないエラーです
"
* },
* )
*/
/ **
* @OAResponse(
* response="default",
* description="Unexpected Error",
* @OAJsonContent(
ref="#/components/schemas/
default_error_response_content")
* ),
* ),

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

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

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

ありがとうございました！
32

Web api開発をするならドキュメントは自動生成にしておこう__ph_per_kaigi2021_

More Related Content

What's hot (20)

Similar to Web api開発をするならドキュメントは自動生成にしておこう__ph_per_kaigi2021_ (20)