これは、公式 Discourse API ドキュメントへの貢献に関するガイドです。
必要なユーザーレベル：Developer
コンソールアクセスが必要です
https://docs.discourse.org の公式 API ドキュメントに貢献したいとお考えですか？このガイドでは、その手順を段階的に説明します。
概要
このドキュメントでは、以下の手順を案内します。
- 前提条件の準備
- Discourse API ドキュメントリポジトリのクローン取得
- API ドキュメントファイルの編集
- ローカルでの変更確認
- プルリクエストの作成
前提条件
Discourse の開発環境がインストールされている必要があります。まだインストールしていない場合は、環境に合ったガイドを こちら のトピックに従ってください。
Discourse API ドキュメントリポジトリのクローン取得
Discourse の開発環境がホームディレクトリ ~/ 内にあると仮定して、以下の手順でリポジトリをクローン取得します。
-
ホームディレクトリから、https://github.com/discourse/discourse_api_docs のリポジトリをクローン取得します。
git clone https://github.com/discourse/discourse_api_docs -
現在、
discourseフォルダとdiscourse_api_docsフォルダが並んでいるはずです。~/discourse/ ~/discourse_api_docs/
API ドキュメントファイルの編集
ドキュメントは ~/discourse/spec/requests/api/ から直接編集する必要があります。
プラグイン API ドキュメントは、plugins/*/spec/requests/api/ にある spec ファイルを通じて貢献することも可能です。
ドキュメントファイルを編集した後、~/discourse/ から以下のコマンドを実行します。
bin/rake rswag:specs:swaggerize && cp openapi/openapi.yaml ~/discourse_api_docs/openapi.yml
ドキュメントは rswag を使用して生成され、~/discourse_api_docs/ にコピーされます。
次に、~/discourse_api_docs/ から YAML ファイルを JSON に変換します。
npm install
node tojson.js
ローカルでの変更確認
更新されたドキュメントを確認するには、以下の手順に従ってください。
-
~/discourse_api_docs/から以下を実行します。npm install node server.js -
http://localhost:3001 にアクセスして、更新されたドキュメントを確認します。
プルリクエストの作成
すべてが正常であることを確認したら、discourse/discourse リポジトリ（Discourse API Docs リポジトリではありません）からプルリクエストを作成します。
discourse_api_docs リポジトリは、最新の Discourse コア仕様に基づいて OpenAPI 仕様を再生成する GitHub Actions ワークフローによって、毎日自動的に更新されます。このリポジトリに別途 PR を提出する必要はありません。
よくある問題と解決策
Discourse API ドキュメントの誤りの報告
Discourse API ドキュメントに問題や誤りが見つかった場合は、Discourse Meta フォーラム で報告してください。効果的な報告方法については、バグ報告ガイド を参照してください。
何か問題がありましたか？