用于swagger api的文档生成器
foliantcontrib.swaggerdoc的Python项目详细描述
用于叶状物的夸张API文档生成器
此预处理器从Swagger规范文件生成标记文档。它使用Jinja2模板引擎或widdershins从夸张的规范文件生成标记。
安装
$ pip install foliantcontrib.swaggerdoc
配置
要启用预处理器，请将pgsqldoc添加到项目配置中的preprocessors部分：
preprocessors:-swaggerdoc
预处理器有许多选项：
preprocessors:-swaggerdoc:json_url:http://localhost/swagger.jsonjson_path:swagger.jsonadditional_json_path:tags.jsonmode:'jinja'template:swagger.j2environment:env.yaml
json_url
：指向swagger规范文件的URL。如果它是一个列表预处理程序，则会获取第一个有效的url。
even though the parameters are called json_url and json_path, yaml format is supported too. Parameters may be softly renamed in future.
json_path
：swagger spec文件的本地路径（相对于项目目录）。
If both url and path are specified — preprocessor first tries to fetch JSON from url, and then (if that fails) looks for the file on local path.
additional_json_path
：仅适用于jinja模式。包含附加信息（相对于项目目录）的swagger规范文件的本地路径。它将合并到原始规范文件中，^ {EM1}$不超过现有字段
mode
：确定如何将放大规格文件转换为降价。应该是：jinja，widdershins之一。默认值：widdershins
jinjamode is deprecated. It may be removed in future
template
：仅适用于jinja模式。用于呈现生成的文档的jinja模板的路径。路径是相对于项目目录的。如果没有指定模板，预处理器将使用默认模板（如果缺少模板，则将其放入project dir）。默认值：swagger.j2
environment
：仅适用于widdershins模式。Widdershins转换器的参数。可以将包含相对路径的字符串传递给具有所有参数的yaml或json文件（如上面的示例所示），也可以在此键下以yaml格式指定所有参数。More info关于widdershins参数。
用法
在文档中应插入生成的文档的位置添加一个<swaggerdoc></swaggerdoc>标记：
# Introduction This document contains the automatically generated documentation of our API. <swaggerdoc></swaggerdoc>
每次预处理器遇到标记<swaggerdoc></swaggerdoc>时，它都会插入整个生成的文档文本，而不是它。swagger spec文件的路径或url取自foliant.yml。
您还可以在标记选项中指定一些参数（或全部参数）：
# Introduction
Introduction text for API documentation.
<swaggerdoc json_url="http://localhost/swagger.json"
mode="jinja"
template="swagger.j2">
</swaggerdoc>
<swaggerdoc json_url="http://localhost/swagger.json"
mode="widdershins"
environment="env.yml">
</swaggerdoc>
标记参数具有最高优先级。
这样，您就可以在一个foliant项目中拥有来自多个不同的swagger spec文件的文档（如果您喜欢，甚至可以在一个md文件中）。
自定义输出
金贾
jinjamode is deprecated. It may be removed in future
在jinja模式下，输出标记由Jinja2模板生成。在此模板中，swagger spec文件中的所有字段都可以在名为swagger_data的字典下使用。
要自定义输出，请创建适合您需要的模板。然后在template参数中提供它的路径。
如果希望使用默认模板作为起点，请在打开swaggerdoc预处理器的情况下构建叶型项目。在第一次构建之后，默认模板将出现在名为swagger.j2的foliant项目目录中。
维德申斯
在widdershins模式下，输出标记由widdershinsnode.js应用程序生成。它支持使用doT.js模板自定义输出。
- 克隆原始widdershinsrepository，并修改位于templates文件夹中的一个子文件夹中的模板。
- 将修改后的模板保存在叶子项目附近的某个位置。
- 在
environment配置的user_templates字段中指定修改模板的路径。例如，如下：
preprocessors:-swaggerdoc:json_path:swagger.ymlenvironment:user_templates:!path./widdershins_templates/
欢迎加入QQ群-->： 979659372
