本指南旨在指导您为官方 Discourse API 文档做出贡献。
所需用户级别：开发者
需要控制台访问权限
您想为 https://docs.discourse.org 上的官方 API 文档做出贡献吗？本指南将逐步说明具体操作方法。
摘要
本文档将引导您完成以下步骤：
- 设置先决条件。
- 克隆 Discourse API 文档仓库。
- 编辑 API 文档文件。
- 在本地查看您的更改。
- 创建拉取请求（Pull Request）。
先决条件
您必须已安装 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/ 编辑文档。
- 在 GitHub 上查看该文件夹：discourse/spec/requests/api at main · discourse/discourse · GitHub
插件 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 文档仓库）创建拉取请求。
discourse_api_docs 仓库会通过 GitHub Actions 工作流每天自动更新，该工作流会根据最新的 Discourse 核心 spec 重新生成 OpenAPI 规范。您无需向该仓库单独提交 PR。
常见问题与解决方案
报告 Discourse API 文档中的错误
如果您在 Discourse API 文档中发现任何问题或错误，请在 Discourse Meta 论坛 上报告 - 您可以参考 错误报告指南 以有效完成此操作。
出了什么问题？