【自分用】OpenAPI仕様の日本語訳

OpenAPIとは

OpenAPI仕様（OpenAPI Specification）は、Linux Foundationの協力プロジェクトであるOpenAPI Initiativeが推進するコミュニティ主導のオープン仕様です。
OASは、HTTP APIの標準的でプログラミング言語に依存しないインターフェース記述を定義します。これにより、ソースコード、追加のドキュメント、ネットワークトラフィックの解析に頼ることなく、人間やコンピュータがサービスの機能を発見し理解することが可能になります。OpenAPIを正しく定義することで、利用者は最小限の実装ロジックでリモートサービスを理解し操作することができます。これは、低レベルのプログラミングにおけるインターフェース記述が果たした役割と同様に、サービス呼び出し時の推測を排除します。

機械可読なAPI定義ドキュメントの利用例には、以下が含まれます（ただしこれに限りません）：
•インタラクティブなドキュメント
•ドキュメント、クライアント、サーバーのコード生成
•テストケースの自動化

OpenAPIドキュメントはAPIサービスを記述し、YAMLまたはJSON形式で表現されます。これらのドキュメントは静的に生成・提供される場合もあれば、アプリケーションから動的に生成される場合もあります。

OpenAPI仕様の特徴

•既存のAPIを再構築する必要はありません。
•任意のソフトウェアをサービスにバインドする必要もありません（記述されたサービスはその記述作成者の所有物である必要はありません）。
•サービスの機能はOpenAPI仕様の構造で記述する必要があります。

ただし、すべてのサービスがOpenAPIで記述できるわけではありません。この仕様はあらゆるHTTP APIスタイルを網羅することを目的としているわけではなく、REST APIのサポートを含んでいます。
また、OpenAPI仕様はデザインファーストやコードファーストといった特定の開発プロセスを強制するものではありません。どちらの手法でも、HTTP APIとの明確なやり取りを確立することでサポートします。

GitHubプロジェクトについて

このGitHubプロジェクトは、OpenAPIを始めるための入口です。ここでは、OpenAPI仕様に関する情報、仕様の簡単な例、およびプロジェクトに関する一般情報を見つけることができます。

バージョン管理

このリポジトリには、すべての公開済みOpenAPI仕様バージョンのMarkdownソースが含まれています。リリースノートやリリース候補バージョンについては、リリースページをご参照ください。
schemasやtestsのようなフォルダには、現在および過去の仕様バージョンに関する資料が格納されています。

実例を確認する

動作例を確認したい場合は、現在の例のリストをご覧ください。

ツールとライブラリ

独自のOpenAPI定義を作成したり、定義を提示したり、その他の用途に利用したい場合は、実装のリストをご覧ください。

参加方法

OpenAPI仕様の開発プロセスはContributing Guidelinesに記載されています。
次期OpenAPI仕様の開発は、技術運営委員会（Technical Steering Committee, TSC）によって指導されています。この委員会は、APIの専門知識を持つコミッターで構成され、コミュニティからのフィードバックを取り入れ、必要に応じてコミッターの拡大を進めます。将来の仕様に関するすべての開発活動は、このブランチにマージされます。将来の仕様がリリースされると、このブランチはmainにマージされます。

TSCは毎週ウェブ会議を開催し、オープンなプルリクエストをレビューし、進化するOpenAPI仕様に関連する問題について議論します。週次会議やスケジュールされた作業セッションへの参加はコミュニティに開かれています。OpenAPIの技術会議カレンダーはオンラインで確認できます。

貢献の手段

OpenAPI仕様の進化に参加したい場合は、以下の行動を検討してください：
•仕様のMarkdownソースやHTMLレンダリング（公式の信頼できるソース、フルクレジットと引用を含む）をレビューする。
•仕様がどのように進化しているかを理解するために、貢献プロセスを確認する。
•議論、問題、プルリクエストをチェックし、自分のアイデアやフィードバックが既に記録されているか確認する。既存の会話に参加するには、関連する問題やPRを購読する。
•CodeTriage.comを通じて、毎日または毎週1件のオープンイシューを購読する。
•新しい懸念を説明する議論を作成する（理想的には関連するユースケースの明確な説明付き）。

すべてのフィードバックが受け入れられるわけではなく、変更が仕様に適切かどうかについて、賛成・反対の堅実な議論が行われる場合があります。

ライセンス

ライセンスについては、Apache-2.0 Licenseをご参照ください。