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

Slide 1

Slide 1 text

Slide 2

Slide 2 text

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

Slide 5

Slide 5 text

Slide 6

Slide 6 text

Slide 7

Slide 7 text

Slide 8

Slide 8 text

Slide 9

Slide 9 text

Slide 10

Slide 10 text

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

Slide 13

Slide 13 text

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

Slide 18

Slide 18 text

Slide 19

Slide 19 text

Slide 20

Slide 20 text

Slide 21

Slide 21 text

Slide 22

Slide 22 text

Slide 23

Slide 23 text

Slide 24

Slide 24 text

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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を使い、　共通化したオブジェクトを呼び出す

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

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種

Slide 30

Slide 30 text

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text