web-services - 从 Python 为 RESTful Web 服务生成文档

Question

关闭。这个问题不符合Stack Overflow guidelines .它目前不接受答案。












想改进这个问题？将问题更新为 on-topic对于堆栈溢出。

4年前关闭。




Improve this question




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

Answer 1

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

在他们的网站上有关于如何设置文档源文件以及将它们构建到完成的文档(如 HTML)的过程的优秀文档。您应该感兴趣的部分是它从 Python 源代码合并文档字符串的系统，我假设您一直在为服务于 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“第一步”文档，重新排序最少。如果看起来可以满足您的需求，请查看该文档和站点的其余部分。