From 9b22157f9d74d7ac8cd97c2f0111b651ce9d81dc Mon Sep 17 00:00:00 2001 From: ma91n Date: Thu, 28 Dec 2023 16:31:53 +0900 Subject: [PATCH] opentelemetry --- .../OpenAPI_Specification_2.0.md | 9 +++++ .../OpenAPI_Specification_3.0.3.md | 34 +++++++++++++------ 2 files changed, 33 insertions(+), 10 deletions(-) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md index 918e9134..8975a2eb 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md @@ -854,6 +854,15 @@ CORS（Cross-Origin Resource Sharing）のために、options メソッドの追 [^1]: https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/enable-cors-for-resource-using-swagger-importer-tool.html +## OpenTelemetry Traceparent HTTP Header + +OpenOpenTelemetryで用いるられる[traceparent](https://www.w3.org/TR/trace-context/) のリクエストヘッダーはOpenAPIで **原則不要** とする。 + +理由は以下である。 + +- OpenTelemetryが定めるヘッダー類は、API横断的に設定されるべきものであり、ミドルウェアやフレームワーク側などでの一律の制御を推奨するため +- 記載することにより、OpenOpenTelemetryに対応していることを明記し開発者に周知できるメリットより、各アプリ開発者が生成されたコードで悩んだり、誤解されることを回避したいため + ## API のバージョン管理 Swagger 定義で以下の変更を行う場合は、利用するコード生成の動作によってはクライアントにとって互換性を失う破壊的変更であることがあるため、変更は調整の上で行うか、バージョンを上げることを考える。 diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index 8b5cf03d..4a5b6e8c 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -745,9 +745,31 @@ tags: # 設計上のポイント -（相談事項） +## CORS + +CORS（Cross-Origin Resource Sharing）のために、options メソッドの追記は **原則不要** とする。 + +理由は以下である。 + +- サーバ側 + - options メソッド対応は、API 使用ではなく実装レベルの機能横断的な処理（Java における Servlet Filter や Spring の Interceptor、Go における Middleware など）で行うことが大半であり、コード生成が不要 +- クライアント側 + - options メソッドを用いるのはクライアントがブラウザであり、クライアントのアプリケーションコードが明示的にアクセスしないため、コード生成が不要 +- 使用面として + - ` Access-Control-Allow-Origin` がどのような値を返すか、呼び出し元によって動的な値を返したい場合があり、記載が困難なケースがある + +ただし、Amazon API Gateway のようなサービスを利用する場合は、options メソッドの記載が必須である場合は除く[^1]。 + +[^1]: https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/enable-cors-for-resource-using-swagger-importer-tool.html + +## OpenTelemetry Traceparent HTTP Header -- 要素規約が「どのように書くか」に焦点を当てているのに対し、そもそも「何を書くか」といった部分については、切り出して要素規約から refer させる形の方がスッキリするかも。要素規約に入れられるならそれでよし。描きながらバランス見て。 +OpenOpenTelemetryで用いるられる[traceparent](https://www.w3.org/TR/trace-context/) のリクエストヘッダーはOpenAPIで **原則不要** とする。 + +理由は以下である。 + +- OpenTelemetryが定めるヘッダー類は、API横断的に設定されるべきものであり、ミドルウェアやフレームワーク側などでの一律の制御を推奨するため +- 記載することにより、OpenOpenTelemetryに対応していることを明記し開発者に周知できるメリットより、各アプリ開発者が生成されたコードで悩んだり、誤解されることを回避したいため ## バリデーションについて @@ -1689,14 +1711,6 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 -# 各種ツール、サービスとの統合 - -特定のツール、サービスに依存する拡張系 - -## oapi-codegen - -## Amazon API Gateway - --- # License