我正在寻找一种方法来获取我的 Discourse 实例中可用的 API 端点的最终列表。在构建集成到平台时，有时很难知道有哪些 API 可用。
5 个赞
我认为这在技术上是不可能的。Discourse 没有 API 发现路由（例如，类似于 WordPress 的 /wp-json 路由）。我所知道的最接近的是 https://docs.discourse.org/ 上的文档。
对于文档未涵盖的集成，要弄清楚它们是否可行，最快的方法可能是在这里询问如何实现某个特定目标。API 的通用规则是，通过 Discourse UI 可以完成的任何事情都可以通过 API 完成。
9 个赞
Simon，感谢您的回复！我熟悉 docs.discourse.org（有趣的是，它并非官方文档，而是 API 规范）。
我也熟悉使用浏览器控制台捕获请求以及浏览 routes.rb 文件。
正如您所能想象的——上述两种方法都非常繁琐，而且不太用户友好。对于我们这些希望快速构建深度集成的人来说——尤其是当我们的公司有其他团队或第三方供应商想要集成时……告诉他们做上述事情，回应非常糟糕。
虽然我了解 Discourse 功能的灵活性，但开发或集成该平台至少可以说是一场艰苦的战斗。作为最后的努力，我希望可能有一种以编程方式聚合公共 API 的方法。
7 个赞
最终的来源，除了来源本身，就是逆向工程 Discourse API。
您可以在前端完成的所有操作都可以通过 API 完成。只有极少数操作只能通过 API 完成。
3 个赞
你能更清楚地说明你的意思吗？
虽然 Simon 指出这些文档不包括通过 Discourse 扩展（例如插件）实现的 API，但这些文档是官方的，因为我们确实维护它们。
这并不是说我们在服务器端 API 文档以及 API 本身方面没有很大的改进空间，但我确实想更好地理解你对现有文档的反馈。
1 个赞
当然！这可能比您要求的要多 
我想您在这里保留了官方产品文档，对吗？
我认为 API 规范 是 文档 的一个子集。所以我总是忘记，当我指向 docs.discourse.org 时，它不会转到 Discourse 文档……它会转到有限的 API 规范集，这让我短暂地感到意外。
所以我告诉他们一些类似的话：
感谢您今天的会面，我很高兴您有兴趣了解您可以使用新的 Netwrix Community 构建什么样的体验！
文档实际上在 https://meta.discourse.org/c/documentation/10。
docs.discourse.org 实际上不是他们的文档，而是他们的 API 规范。我知道您询问了与我们正在构建的新社区集成的事宜。不幸的是，我没有一个页面可以指向您，展示 Discourse 提供的所有功能，但您可以访问 docs.discourse.org 来了解其中一些可能的功能。
在这种情况下，由于我无法为他们提供一份明确的现有端点列表，我只是告诉他们：“假设您能想到的一切都是可能的。我会出去看看 Discourse 能做什么，如果需要，我们可以从中进行筛选。”
但是，如果所有 API 都列在规范中，那将是很好的，不是吗？
更多背景……
如果我买了一辆车，他们给了我一张功能表，我问：“太棒了！这就是全部了吗？”
“嗯，不是……但是如果你看看引擎盖下面，追踪一下 12v 电线和发动机周围的软管夹，你应该能看到它们连接到哪里，并逆向工程出它还能做什么。”
当然，在这种情况下，机械师/开发人员/技术人员可以做到这一点。但不是每个人 
而且，即使作为一名开发人员，我也不想：
- 学习 Ruby 来查看可能存在哪些路由
- 逆向工程所有 routes.rb 文件以了解可用的端点
- 进一步细化逆向工程，以找出它们需要什么输入，输出的对象结构是什么
- 查看我有哪些插件
- 在我的日常工作和这件事之间重复（我想？我不会 Ruby，所以我也不确定）
- ……六个月后，我得到了一个答案。
我之所以这样说，是出于喜爱——当今没有哪个平台能与 Discourse 平台的能力相提并论。绝对没有。 它是市场上最强大、最灵活、最具成本效益的产品，远远领先于竞争对手。
它的缺点不是它的健壮性、强大性和灵活性。事实上，这些是 Discourse 的一些最大优势，竞争产品将难以甚至无法模仿。
- 并不是它的 API 不好——而是找到它们很困难。
- 并不是拥有许多选项的管理面板使采用变得困难，而是缺乏教育和管理设置名称，如
First post only，这些名称充其量是模糊的。 - 并不是它对类别、主题和标签的社区工具结构的强大而简单的（而且非常完美！）实现，而是信息不存在，无法教育和启发用户，让他们知道它不必是一个类别，而可以是一个博客、一个产品公告板或一个想法门户……而且它们不必是主题，而是可以是博客、产品公告和想法。
对我来说，这是 Discourse 作为产品唯一缺乏的东西：润色——最后的细节。
9/10，会再次购买。
7 个赞
好的，我想我明白了，谢谢。
接下来是我个人的看法——我还没有与比我更了解情况的人讨论过这些，所以我可能会在一些地方被纠正。
我们的故事文档也在不断发展。我们已经取得了显著的进步，但还有很长的路要走。请允许我试着总结一下。
首先，作为一种更高层次的思维模型，我会这样描述：
- 正如您指出的，我们文档的主要入口在这里：Documentation - Discourse Meta
我倾向于将 API 文档称为“文档”（docs），而不是“规范”（specs），但我同意它们仍然是我们开发者文档的一个子集。这些文档的 URL 有点奇怪……我们的全部文档应该放在那里，或者那里应该重定向到 https://meta.discourse.org/c/documentation/10，并且从 Introduction to Discourse Development 有一个清晰的指向 API 文档的标记。
我们的开发者文档本身也在不断改进。这里的提交历史可能最能说明到目前为止的努力方向：Commits · discourse/discourse-developer-docs · GitHub
API 文档可以被描述为不完整，但我们需要努力使我们的情况在这里变得清晰。过去，我们曾指向“逆向工程 API”，但我同意这不是一个好方法。对于自行承担风险进行黑客攻击来说还可以，但可能存在一些端点未在此列出，最好不要依赖它们。
服务器端 API 主要 intended 被我们的前端应用程序使用。在前端，我们提供了一个 JavaScript API，它将是一个更好的接口，因为它可以隐藏后端所做的更改：Using the JS API
那么，我们可以对我们的后端 API 做出哪些稳定性保证呢？
我认为这是 API 文档应该解决的责任。理想情况下，那里记录的是我们支持的所有端点的一个子集，但这是一个有意的子集，我们旨在支持其他构建集成的人，而未在此列出的内容则有意不被记录为仅 intended 为我们的前端提供，这些内容可能会在不通知的情况下更改。
理想情况下（在我看来），文档应该内置到源代码中，这样文档本身就可以得到测试，可以通过插件进行扩展，由应用程序本身提供服务，从而与正在记录的实例同步——这样您就可以查看给定站点的 API 文档，并查看其运行版本以及实际安装和启用的任何插件的文档。
我知道内部还有其他人对改进我们的服务器端 API 方案有很多讨论。
我们还无法在此领域投入太多精力，因为在过去几年里，我们开发者体验的主要重点一直是现代化我们的前端。
我不确定何时可能会改变，但我们会留意我们可以做的一些小事情，以逐步改进服务器端 API 的情况。如果出现具体问题，也许我们可以利用这些问题作为契机，在此期间进行更有针对性的改进。
5 个赞
稳定性保证应通过简单的 API 版本控制来解决。
这个主题不是关于文档的去向——而是关于 API 如何 被记录。缺失的是像 OpenAPI 这样的标准化、机器可读的格式。
这种缺失，加上缺乏版本控制，使得集成工作比应有的更困难、更脆弱。即使是已记录端点的基本 OpenAPI 模式也会非常有帮助。
3 个赞
从根本上说，这不是一个文档问题，而是一个实现问题。
@avdi 多年前就提出了这个问题，并且内部普遍认为正确的解决方案是建立一个拥有统一参数和数据结构的、经过版本控制的 JSON/REST API。
目前，我们提供的 API 是我们的内部 API。它 100% 完整且详尽，但它使用起来很麻烦，并且数据结构会发生变化。它返回的数据结构和端点都是为驱动客户端 Ember 应用而优化的。随着时间的推移，它会不断演变和改变结构，这使得依赖它来完成关键任务变得很棘手。在此基础上进行开发比实际需要更复杂。
一套全新的控制器和路由将解决这里的稳定性问题，并允许我们返回更适合 REST API 的数据结构。例如：
/api/v0/topic/1234.json 可以返回一个“与通用 API 实践一致”的结构。
我们的 topic json 中有太多非常复杂的“仅限 Ember 客户端的考虑因素”：
timeline_lookup、post_stream、tags_descriptions 等等……
话虽如此，这是一个巨大的项目，我们需要大量的内部重新设计，以确保我们不会重复逻辑。此外，插件使这个问题更加复杂，因为它们会重塑许多内部行为，而这些行为需要在 API 中得到反映。（assign 对这些结构有什么影响？）
我当然认为我们会着手进行这项工作，但不会在不久的将来。
10 个赞
我认为变化需要时间这是完全合理的。我在上一家公司负责Developer Relations，天啊……我们的API改善花费了超过两年的时间。所以有很多复杂的事情需要考虑（工程团队也讨厌创建一个不能变更的稳定端点！）
不过我确实认为一些小的变化可以随着时间的推移在较短的时间内发生。老实说，我还没有仔细研究你的路由（或者Ruby中的路由）是如何定义的——但我假设一些简单的事情可以相当容易地处理。例如：
我不能代表所有人发言，但我觉得即使你的当前API规范中存在端点——即使没有描述和示例，即使响应模型是流动的——这也是一个很大的胜利。仅仅知道某些内容存在，有时候就已经算一半的胜利了。
5 个赞
API 文档是 OpenAPI 格式的吗？
https://docs.discourse.org/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Discourse API Documentation",
"x-logo": {
"url": "https://docs.discourse.org/logo.svg"
},
"version": "latest",
...
6 个赞
我必须羞耻地承认，我从未注意到这一点…
感谢@blake指出这一点。
2 个赞