From d955c4dba96b1edf889a629975f010280672aa8b Mon Sep 17 00:00:00 2001 From: ma91n Date: Fri, 15 Dec 2023 13:59:52 +0900 Subject: [PATCH 1/2] Add Callback --- .../OpenAPI_Specification_3.0.3.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index a89919c9..192fccda 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -589,6 +589,33 @@ securitySchemes: description: 'Bearer トークン認証' ``` +### links + +[links](https://swagger.io/docs/specification/links/) は OpenAPI 3.0 の新機能の1つで、あるAPIレスポンスの値を用いて、別のAPIを呼び出す方法を明示できるセクションである。 + +興味深い機能であり、APIのセマンティクスを伝えるのに有用であるが、本規約では記載しないことを推奨とする。 + +理由は下記の通りである。 + +- 業務システムでは、業務フローを抑えておけば、API操作フローの理解はそこまで難しくないことが多い + - 逆に、API同士の関係だけを示すだけでは業務モデリング図とのダブルメンテナンスになったり、中途半端になりうる +- [OAS 3.0 Support Backlog](https://github.com/swagger-api/swagger-ui/issues/3641) にあるように、2023/12/15時点ではSwagger-UIが対応していない + - linksを書いたと言って、APIドキュメントに影響しない + +### callbacks + +[callbacks](https://swagger.io/docs/specification/callbacks/) は OpenAPI 3.0 の新機能の1つで、APIサーバ側が指定されたコールバックURLを呼び出すという仕組みである。 + +仕様書には、ECショップで購入のたびにマネージャーに通知を送るといった、何かしらの処理をトリガーにコールバックURLを呼び出す例が示されている。 + +利便性は高い仕様だが、本規約では記載しないことを推奨とする。 + +理由は下記の通りである。 + +- コールバックURL呼び出しの、エラーハンドリングが難しい +- 業務システムでは欠損が許されない、または将来的に許されなくなる可能性があり、その場合にこの機能に頼ると想定異常の追加作業が発生する + +コールバックのような仕組みを実現するには、別途キューイングのメッセージサービスの利用などを検討する。 ## security From bf384fbc2902ce2d9868e2d515f2a71cfa855a1d Mon Sep 17 00:00:00 2001 From: Junki Mano Date: Fri, 15 Dec 2023 15:07:18 +0900 Subject: [PATCH 2/2] Update OpenAPI_Specification_3.0.3.md --- .../forOpenAPISpecification/OpenAPI_Specification_3.0.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index 192fccda..8052d642 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -613,7 +613,7 @@ securitySchemes: 理由は下記の通りである。 - コールバックURL呼び出しの、エラーハンドリングが難しい -- 業務システムでは欠損が許されない、または将来的に許されなくなる可能性があり、その場合にこの機能に頼ると想定異常の追加作業が発生する +- 業務システムでは欠損が許されない、または将来的に許されなくなる可能性があり、その場合にこの機能に頼ると想定以上の追加作業が発生する コールバックのような仕組みを実現するには、別途キューイングのメッセージサービスの利用などを検討する。