Fosrestbundle: REST API 文档生成路由

查看http://getfrapi.com/截屏视频以获得一些灵感。

我已经看过了。 但我不喜欢他们实现的很多东西。 首先，他们的 REST 不是 RESTful :-D

“灵感”，我不是在谈论他们的休息，而是他们的文档（和测试）一代:)

我个人不喜欢它，但我们可以讨论 WADL 格式的文档的生成吗？

http://www.w3.org/Submission/wadl/

我想知道是否比生成更好的方向是提供一些允许快速构建文档控制器/视图的视图助手。 这似乎比简单地生成一个结构更好，并且更具可扩展性/可维护性。 换句话说，我认为生成 API 文档非常适合 FRAPI 的用例（放入应用程序），但质疑我们是否需要“按原样”使用此功能，或者它是否有意义。

我们是在为客户讨论文档吗？

请记住，这就是 REST 试图避免的 :)

odino：当然。 但是有些事情是这样的，即使您遵循 HATEAOS，您也需要检查标头。 此外，虽然您应该知道期待不同的状态代码，但知道哪些状态代码“更有可能”仍然很好。 它非常适合随意审查 API。

还有另一个应该被忽略的话题：一些客户就像砍树一样，不必浪费大量时间来填写这一页纸：）

同意，我们唯一应该避免的是严重依赖生成的文档，否则我们会复制 WSDL

不赞成砍树者 :)

据我所知，真正的 REST API 文档是关于定义媒体类型及其关系，而不是 URL。 例如http://kenai.com/projects/suncloudapis/pages/Home , http://amundsen.com/media-types/collection/

但是对于简单的 HTTP API，80% 的 Web 项目都会出现这种情况，这个特性仍然有用。

是的 vladar，URI 模板显然是邪恶的。 但是如果我们需要开发一个 REST 包，我们应该遵循这些原则。

URI 模板非常适合 ApiBundle

可能能够从http://swagger.wordnik.com/获取概念

:+1: 招摇。 这看起来棒极了！

为了创造类似的体验，我们可能能够：

• 解析标记为@apidoc或其他东西的方法
• 从@apidoc标记的方法上的 docblock 获取方法和参数的描述
• 允许基于每个操作对调用进行内联测试。

总而言之，我认为实现像 Swagger 这样的屏幕是非常可行的，并且对于这个 Bundle 来说很有意义。

另一种选择是简单地生成 Swagger 使用的 JSON，但它带有一些权重（Java）......宁愿看到“喜欢”的实现。

生成兼容的 JSON 是我的第一个想法。 周末我会更深入一点，也许有一些快速的'n脏原型可能。

@pminnieur似乎我们可以轻松地提供相同的基本功能而不是集成。

至少它可以像https://github.com/FriendsOfSymfony/FOSJsRoutingBundle一样工作——只需添加一些精美的 HTML/CSS 并使用某种 API 文档公开您的 RESTful 路由。 也许我们可以使用一些注释来支持更多信息。

我想从这个开始，但我认为将代码放入专用包（例如 FOSRestAPIExplorerBundle）会更好。 问题是，我们应该只支持 Swagger API（因此 Swagger 用于可视化收集并以 JSON 形式公开的信息）还是我们也应该提供我们自己的 Web 界面？

一个单独的 Bundle 听起来是个好主意。 如果我们只支持 swagger，我们可能想在 Bundle 名称中这样说。 我不知道我们是否也想支持其他东西。 取决于你的动机和招摇的质量。 关于 swagger 的一个问题：它如何与不想暴露给外部服务的内部 API 一起工作？

我认为，如果您不想公开返回 Swagger JSON 的 URL，我认为您根本不必公开它……：D 说真的，我想使用注释，如果您不希望路由成为公开的，您不会添加@Expose()注释或添加@Expose(false) —— 类似这样的东西。 就像 FOSJsRoutingBundle 是可配置的，如何处理它（默认公开所有内容，或公开白名单）。 如果您的意思是“这是我们公共 API 的链接，并且此链接仅供您使用”，我们可能会添加一个注释，如@Api("public")和@Api("private")包括安全组件，以便您可以分发不同的 API向不同的人提供文档（并控制对他们的访问）。

对于名称：我想要一个通用名称，Swagger 将是第一个受支持的 API 文档服务。 如果人们想添加任何其他服务，他们可以这样做（并且不能从头开始）。 例如， @odino可以添加 WADL 支持。 至少我也想提供一个网络界面。

到目前为止，我创建了一个 GitHub 存储库，以便在开始之前收集想法和问题。 随时为任何要讨论的问题或主题打开问题（当然也可以讨论命名）;-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

好的好的。 一旦事情成型..我们可以将其移至 FOS

您是否打算利用https://github.com/wordnik/swagger-ui作为“显示器”？

首先，是的。 只生成要被 swagger-ui 使用的 swagger-spec 一致的 json。

支持https://github.com/nelmio/NelmioApiDocBundle

我知道这已经很老了，但是从那以后有些事情发生了变化，我在寻找 Swagger / Openapi 的包/捆绑包时相对较快地发现了这一点。
有机会重新考虑这个吗？ 由于 NelmioApiDocBundle 已被放弃，我看不到任何真正的替代方案可以集成到 Symfony 中用于 Swagger / OpenApi（或任何其他真正的 RAML，...？）。