如何记录基于 Symfony 的 REST API（类似于 enunciate 的文档功能）答案

【问题标题】：How to document a Symfony based REST API (similar to enunciate's documentation capabilities)如何记录基于 Symfony 的 REST API（类似于 enunciate 的文档功能）
【发布时间】：2010-05-03 08:49:45
【问题描述】：

如果我有一个使用 Symfony [symfony-project.org] 框架（即 PHP）编写的基于 REST 的服务，是否有任何合适的工具/框架可以解析我的代码并生成 API 文档？

基于 Java 的框架 enunciate 具有类似于我需要的文档功能，您可以在此处查看示例：http://enunciate.codehaus.org/wannabecool/step1/index.html。

我了解基于 REST 的服务的前提应该是不言而喻的，但是我正在寻找可以为我生成此文档而无需手动编写所有端点、支持的格式、示例输出等的东西。

谢谢

【问题讨论】：

标签： php rest symfony1 documentation-generation enunciate

【解决方案1】：

不确定您以前是否见过Swagger。他们似乎有一个PHP compatible version，尽管我不能亲自担保。它会自动生成一些类似于 enunciate 的 API 文档，尽管它看起来确实需要通过 PHP cmets 进行一些繁重的手动文档。话虽如此，我认为手动工作与通过 wiki 页面制作自己的工作相同或更少，而且输出要好得多。

事实证明，它看起来像 Enunciate has indefinite plans to eventually support other platforms，但 relevant Jira ticket 目前开放等待赞助商接手工作。

来自ENUNCIATE-356 Jira ticket：

支持其他语言的第一步是将 Enunciate 模型与 Java 模型分离。这项工作正在ENUNCIATE-584 进行跟踪和记录。不幸的是，由于它的重量，它从未脱离调查阶段。除非找到这项工作的赞助商，否则我预计不会很快承担这么重的负担。

编辑：
找到similar question，其中someone mentions 和GitHub project dedicated to Swagger+Symfony2。 This other question 相同，但没有额外信息。

【讨论】：

注意：NelmioApiDocBundle 适用于 Symfony 2
@j0k 啊，是的。著名的。谢谢！

【解决方案2】：

据我所知，没有办法自动化媒体类型的文档。

如果您使用像 XHTML 这样的媒体类型，那么像 Google sitemap 这样的网络爬虫可能会产生一些有用的输出来显示您的资源之间的关系。

【讨论】：