从Python生成RESTful Web服务的文档

Question

我希望能够为一个用Python编写的RESTful Web服务API生成文档。理想情况下，它应该看起来像Yahoo的RESTful Web服务文档。有没有人有任何想法或参考资料？

- bobuva

Answer 1

The Sphinx项目（www.sphinx-doc.org）是Python文档编写的最新技术。它非常强大和灵活，但也有点令人困惑。不过，我认为这是你最好的选择。

他们网站上有很好的文档，介绍如何设置文档源文件以及将它们构建成完成的文档，例如HTML。你应该感兴趣的部分是它的文档字符串系统，可以将Python源代码中的文档字符串整合进来，我假设你已经在使用这种方法为处理REST请求的方法编写文档字符串。请注意，这并不会自动解释正在发生的事情，但会带来所有命名元素及其参数（如果适用），并为你提供适当文档的良好框架。

假设你的所有REST功能都在一个名为restapi.py的模块中，并且它只是位于你的项目的src目录中，那么你需要做两件事才能让Sphinx自动生成文档：

首先，在conf.py中包含autodoc扩展程序并将src目录添加到Sphinx的路径中：

import sys, os
sys.path.append(os.path.abspath('sphinxext'))
extensions = ['sphinx.ext.autodoc']

sys.path.append(os.path.abspath('src'))

然后在Sphinx中

.. automodule:: restapi
    :members:

注意：此信息直接从Sphinx“First Steps”文档中提取，并进行了最少的重新排列。如果这似乎符合您的需求，请查看该文档和网站的其余部分。

- stw_dev

Answer 2

听起来你并不是在构建一个REST API，而只是在做一个RPC。一般来说，组装一个REST API并没有简单的自动化方式，它应该主要是对媒体类型的描述。

如果你的意思是想要将服务中的所有URI汇总到一个API文档中，那完全不符合REST的原则，因为这样会导致URI与资源之间产生过多的耦合。

- aehlke

Answer 3

很遗憾，我不知道有什么具体的东西可以帮助你在Python方面 -- 然而，作为参考点，你可以看一下JAX-RS Java规范使用的WADL规范 -- https://wadl.dev.java.net/ -- 此外，还有一个xslt可以将wadl转换成html -- http://www.mnot.net/webdesc/

他们使用雅虎REST API作为示例。

- Mark