web-services - Generating documentation for a RESTful Web Service from Python

Question

I would like to generate documentation for a RESTful web service API that is written in Python. Ideally it would look like Yahoo's RESTful web service docs. Does anyone have any ideas or references?

Answer 1

Sphinx 项目 ( www.sphinx-doc.org ) 是 Python 文档中当前最先进的。它真的很强大和灵活......所以也有点令人困惑。不过，我认为这是你最好的选择。

在他们的网站上有关于如何设置文档源文件以及将它们构建到完成的文档（如 HTML）的过程的优秀文档。您应该感兴趣的部分是它从 Python 源代码合并文档字符串的系统，我假设您一直在为服务于 REST 请求的方法做这件事。请注意，这不会神奇地解释正在发生的事情，但会带来所有命名元素及其参数（如果合适），并为您提供一个很好的框架来放入适当的文档。

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

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

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

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

然后在狮身人面像

.. automodule:: restapi
    :members:

注意：此信息直接取自 Sphinx“第一步”文档，重新排序最少。如果看起来可以满足您的需求，请查看该文档和站点的其余部分。

Answer 2

听起来您不是在制作 REST API，而只是在制作 RPC。通常没有简单、自动化的方法来组装 REST API，它应该主要是对您的媒体类型的描述。

如果您的意思是您希望将服务中的所有 URI 组合在一起并将它们放入 API 文档中，那么这根本不是 REST，因为从 URI 到资源的所有耦合。

Answer 3

不幸的是，我不知道任何具体可以帮助您在 Python 中的具体内容——但是，作为参考点，您可能会在 JAX-RS java 规范正在使用的 WADL 规范上达到顶峰——https://wadl。 dev.java.net/ -- 此外，还有一个 xslt 可以将 wadl 转换为 html -- http://www.mnot.net/webdesc/

他们使用 yahoo REST API 作为示例。