search

commew / timelogger-web

時間記録アプリ
https://timmew.commew.net
MIT License
2 stars 0 forks source link

アカウント関連のAPIの設計を追加 #58

Closed keitakn closed 1 year ago

keitakn commented 1 year ago

issueURL

https://github.com/commew/timelogger-web/issues/48

この PR で対応する範囲 / この PR で対応しない範囲

https://github.com/commew/timelogger-web/issues/48 の完了の定義にある通り以下の2つのAPIの設計を対応しました

MockServerの起動やTypeScriptの型定義を生成する課題は以下のissueで対応予定ですので、このPRでは実施しません。

Storybook の URL、 スクリーンショット

UI変更はないのでなし。

変更点概要

アカウント関連のAPIの設計を追加しました。

OpenAPIを利用しており src/docs/reference/openapi.yaml にAPI定義を追加してあります。

https://stoplight.io/studio を利用して作成しました。

下記にそれぞれのAPIのリクエスト・レスポンスのサンプルを追加してあります。

サンプルリクエスト・レスポンス

https://stoplight.io/studio で src/docs/reference/openapi.yaml を開くと MockServerが http://127.0.0.1:3100 で起動しますので動作確認はこちらで行いました。

Prefer Headerを追加する事で任意のサンプルを返すようになります。

アカウント登録

正常系

curl -v \
-X POST \
-H "Prefer: code=201, example=ExampleSuccess" \
-H "Content-Type: application/json" \
-H "Authorization: Basic YWRtaW5Vc2VyOnBhc3N3b3JkMTIzNA==" \
-d '
{
  "sub": "99999999999999999999999999999",
  "provider": "google"
}
' \
http://127.0.0.1:3100/accounts | jq

HTTP/1.1 201 Created

{
  "id": 1,
  "name": "NekoKoneko",
  "openIdProvider": [
    {
      "sub": "10769150350006150715113082367",
      "provider": "google"
    }
  ]
}

異常系（認証エラー）

curl -v \
-X POST \
-H "Prefer: code=401, example=ExampleUnAuthenticated" \
-H "Content-Type: application/json" \
-H "Authorization: Basic YWRtaW5Vc2VyOnBhc3N3b3JkMTIzNA==" \
-d '
{
  "sub": "99999999999999999999999999999",
  "provider": "google"
}
' \
http://127.0.0.1:3100/accounts | jq

HTTP/1.1 401 Unauthorized

{
  "type": "UNAUTHENTICATED",
  "title": "Basic Authentication parameters are incorrect."
}

バリデーションエラー

curl -v \
-X POST \
-H "Prefer: code=422, example=ExampleValidationError" \
-H "Content-Type: application/json" \
-H "Authorization: Basic YWRtaW5Vc2VyOnBhc3N3b3JkMTIzNA==" \
-d '
{
  "sub": "99999999999999999999999999999",
  "provider": "google"
}
' \
http://127.0.0.1:3100/accounts | jq

HTTP/1.1 422 Unprocessable Entity

{
  "type": "UNPROCESSABLE_ENTITY",
  "title": "Unprocessable Entity.",
  "invalidParams": [
    {
      "name": "sub",
      "reason": "sub is required."
    },
    {
      "name": "provider",
      "reason": "invalid provider format."
    }
  ]
}

アカウント取得

正常系

curl -v \
-H "Prefer: code=200, example=ExampleSuccess" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMDMxMjM2MjYxNjQzODE2MjQ1OTMiLCJwcm92aWRlciI6Imdvb2dsZSIsImV4cCI6MTY4MzczMTMyMywianRpIjoiMzU2N2RiMjctMzNkZS00MjE3LThjOWYtNTg4YWI1ZDA3YWRkIiwiaWF0IjoxNjgxMTM5Mzk2fQ.qbCDlBuENt_QdGKPIY4LZNtkroOTTIF2y8bhelmpjOw" \
http://127.0.0.1:3100/accounts | jq

HTTP/1.1 401 Unauthorized

異常系（認証エラー）

{
  "type": "UNAUTHENTICATED",
  "title": "Account is not authenticated."
}

OpenAPIの設計方針

あまり厳密にルールを定めている訳ではないですが、基本方針を以下に記載します。

これらのルールに関しては 【OpenAPI】Stoplight Studioを活用して快適＆高速にAPI定義を書く方法｜Offers Tech Blog を参考にしました。

ちなみにAPIのエラーフォーマットは RFC7807 をベースにしています。ぼくのかんがえたさいきょうの API エラーレスポンスのフォーマット という記事を参考にしました

レビュアーに重点的にチェックして欲しい点

アカウント登録、アカウント取得API、OpenAPIの設計方針に問題がないかご確認をお願いします。

GitHubで見ていてもイメージが付きにくいと思うので、何かOpenAPIを閲覧出来るエディタ等で見たほうが分かりやすいかと思います。

※ https://stoplight.io/studio をダウンロードして開いて頂くで問題ありません。

補足情報

インラインコメントをご確認下さい。

vercel[bot] commented 1 year ago

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Comments Updated (UTC)
timelogger-web ✅ Ready (Inspect) Visit Preview 💬 Add feedback Apr 19, 2023 4:44am
HaruyaFujimoto commented 1 year ago

@keitakn コメントについてお早いご対応ありがとうございました！ LGTM です！ LGTMeow