Question

我想为使用Python编写的RESTful Web服务API生成文档。理想情况下，它看起来像雅虎的RESTful Web服务文档。有没有人有任何想法或参考？

Answer 1

Sphinx项目（http://sphinx.pocoo.org/）是Python文档中当前最先进的项目。它非常强大和灵活......所以也有些令人困惑。不过，我认为这是你最好的选择。

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

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

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

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“First Steps”文档，只需最少的重新排序。如果看起来它可以满足您的需求，请查看该文档和网站的其余部分。

Answer 2

不幸的是，我不知道具体哪些内容会特别对Python有所帮助 - 但是作为参考点，你可能会在JAX-RS java规范使用的WADL规范中占据一席之地 - {{3另外，还有一个xslt会将wadl转换为html - https://wadl.dev.java.net/

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

Answer 3

听起来你没有制作REST API，只是简单地使用RPC。通常没有简单，自动的方式来组装REST API，主要应该是对媒体类型的描述。

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

从Python生成RESTful Web服务的文档

3 个答案: