Add Callback, Links

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