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

2019年7月28日 190次阅读

我想为使用
Python编写的RESTful Web服务API生成文档.理想情况下,它看起来像雅虎的RESTful Web服务文档.有没有人有任何想法或参考？ 最佳答案 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”文档,只需最少的重新排序.如果这似乎符合您的需求,请查看该文档和网站的其余部分.

点赞