如何为基于Symfony的REST API编写文档（类似于enunciate的文档功能）

Question

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

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

我理解REST服务的前提应该是自证明的，但我需要的是能够为我生成这些文档，而无需手动编写所有我的端点、支持的格式、样本输出等。

谢谢

- Dominic

Answer 1

不确定您是否见过 Swagger . 它们似乎有一个 PHP兼容版本, 尽管我个人无法保证它的质量。它可以自动生成一些API文档，与enunciate相似，但是看起来需要通过PHP注释进行大量手动编写文档。话虽如此，我认为手动编写的工作量将与通过wiki页面制作自己的文档相同或更少，并且输出结果要好得多。

仅作为一个小知识点，看起来 Enunciate 有无限计划 最终 支持其他平台, 但相关的Jira工单目前为 打开 等待赞助商承担工作。

从ENUNCIATE-356 Jira工单中：

支持其他语言的第一步是将Enunciate模型与Java模型解耦。这项工作正在ENUNCIATE-584上跟踪和记录。不幸的是，由于其繁重性，它从未走出调查阶段。除非找到该工作的赞助商，否则我不希望很快承担这个沉重的负担。

编辑：
发现一个类似的问题，其中有人提到一个专门用于Swagger+Symfony2的GitHub项目。这个问题也是一样的，但没有额外的信息。

- Patrick

---

注意：NelmioApiDocBundle适用于Symfony 2。 - j0k

Answer 2

据我所知，目前还没有自动化文档媒体类型的方法。

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

- Darrel Miller