`swagger.yaml`精査

[H1rono]

随時更新

• RequestとRequestDetailでpropertiesとamountの整合性が取れていない RequestResponse.Filesがない #876 (comment)

[H1rono]

• router/tag.goにだけDescriptionの項がある router.TagにあるDescriptionフィールド #884
• swaggerのcomponentsにあるnewtypeたち
  • UserID(GroupIDとかはない), Target
• naming conventionがまずい(Hoge/HogeDetail vs HogeOverview/Hoge) router以下のリクエスト/レスポンス構造体をrenameする #885
  • Gorouter/group.go: Group(Group作成・更新用), GroupOverview, GroupDetail router/group.goの構造体をrename #886
  • Gorouter/request.go: Request(Request作成用), PutRequest, RequestResponse, RequestDetailResponse
  • Gorouter/tag.go: Tag(Tag作成用), TagOverview router/tag.goの構造体をrename #887
  • Gorouter/transaction.go: Transaction(レスポンス用), TransactionOverview(Transaction作成用), TransactionOverviewWithOneTarget router/transaction.goの構造体をrename #888
• group API
  • memberとownerのCRUDが/groups/{id}/members, /groups/{id}/ownerにあるのはおかしい気がする
• file APIはどうして/requests以下にないんだろうか
• GET /files/{id}のcontent-typeがswagger上では常にapplication/octet-streamになってる GET /files/{fileID}のcontent-typeについて補足 #889
  • 実際はそんなことなく、適切なMIMEが付いている
  • ドキュメントを書くべき
• swaggerのFileMetaにcreated_byのフィールドがない(Goの実装ではある)
• GoのPostRequestでcreated_byがフィールドにあるのはおかしい
  • cookieからIDを取ってくるべき
• PUT /requests/{id}にPostRequestのschemaを使い回している
  • 用途が違うんだから分けて書いた方がいいのでは?
• swaggerのRequestTargetがRequestTargetDetail作成・更新用のエンティティだということがわかりづらい
• (swagger,Go両方)Request/RequestDetailのフィールド順
  • Request: id,status,created_by,title,content,created_at,updated_at,targets,tags,group
  • RequestDetailに追加のフィールド: statuses,comments,files
• GoのRequest構造体をPostRequestにrenameしたほうがいい
• swaggerのPostRequest.requiredに不要なフィールドが指定されている
• swaggerのTransaction.required, PostTransaction.required, PostTransactionWithOneTarget.requiredがおかしい
• (swagger,Go両方)Transactionのフィールド順
  • id,title,amount,target,request,tags,group,created_at,updated_at
• GoのTransactionがresponse用の構造体だとわかりづらい(TransactionResponseにする)
• POST /transactionsが実は複数のtransactionを生やせるエンドポイントだとわかりづらい
  • ドキュメントを書くか、一度に一つのtransactionしか生やせないようにするか
• swaggerのPostTransactionWithOneTargetはPUTに使われているのでPutTransactionWithOneTargetに改名する
• GET /requests/{id}/comments, PUT /requests/{id}/comments/{id}, DELETE /requests/{id}/comments/{id}があってもいいんではなかろうか
• Request Statusの状態遷移に関するドキュメントはどこですか → swaggerのPUT /requests/{id}/statusにあった
• 状態の更新APIはPUT /requests/{id}/statusではなくPOST /requests/{id}/statusの方が適切に見える
  • 確かにRequest.statusを更新しているが、Requests.statusesに新たな項目が増えるため
• StatusとCommentの関係がわからん → わかった
  • swaggerではStatusDetailにcommentsのフィールドが生えているが、RequestDetail.commentsから辿ることはできない
  • 実装ではPutStatusを受け取った後の処理でStatusとCommentの両方を作成している
• swaggerのPutUser使われてない
  • PUT /users/meでPutUser.adminを抜いて使うと良さそう
• DELETEのレスポンス ステータスコードが200と204の2パターンある

[H1rono]

:wa_deka: