如何从 OpenAPI 3.0 生成 PDF 或标记？答案

【问题标题】：How to generate a PDF or markup from OpenAPI 3.0?如何从 OpenAPI 3.0 生成 PDF 或标记？
【发布时间】：2019-06-13 01:31:09
【问题描述】：

我有一个 OpenAPI 3.0 规范，我想从中生成一个 PDF，以便将它提供给最终用户。

目前，swagger-spec-to-pdf 或 swagger2markup 等工具仅支持 Swagger 2.0，不支持 OpenAPI 3.0。是否可以从 OpenAPI 3.0 规范生成 PDF 而无需将其转换为 Swagger 2.0？

【问题讨论】：

OpenAPI 工具列表 - openapi.tools

标签： swagger openapi

【解决方案1】：

您可以使用this site 并将您的 OpenAPI 3.0 规范（以 json 格式）直接发布到其中。我认为这是最简单的方法，并且生成的 PDF 看起来很漂亮。

【讨论】：

在使用具有 3 个定义的 OpenAPI "3.0.1" 规范时表现不佳

【解决方案2】：

以下 2 个包帮助我从 OpenAPI json 文件生成 PDF：

org.openapitools:openapi-generator-gradle-plugin:5.0.0-beta2
org.asciidoctor:asciidoctor-gradle-jvm-pdf:3.2.0

应用相关的插件类，剩下的就是非常简单的任务配置。这是我的 groovy 插件，但如果您需要，应该不难找到相应的 gradle DSL 扩展。

project.plugins.apply OpenApiGeneratorPlugin
GenerateTask adoc = project.tasks.withType(GenerateTask).iterator().next()
adoc.with {
    it.input = swagger.outputDir.path + '/' + swagger.outputFileName + '.json'
    it.generatorName.set 'asciidoc'
    it.outputDir.set swagger.outputDir.path

    // Leaving the below option empty can cause rendering issues
    it.configOptions.putAll([
        'infoUrl'  : 'https://example.com',
        'infoEmail': 'inbox@example.com',
    ])
}

project.plugins.apply AsciidoctorJPdfPlugin
project.tasks.withType(AsciidoctorPdfTask).iterator().next().with {
    it.sourceDir = adoc.outputDir
    it.outputDir = it.sourceDir
}

如果有关于这个 sn-p 的问题（或语法错误），请告诉我。

【讨论】：

【解决方案3】：

我刚刚发现RapiPDF 能够从 OpenAPI 3.0 定义生成 PDF。

但它仍然不是我正在寻找的理想工具。到目前为止，我发现了这些限制：

无 CLI，仅在浏览器中运行。所以我不能在自动化管道中使用它。
不支持回调
生成的文档中没有示例

【讨论】：

【解决方案4】：

一种可能的解决方案是将您的 OpenAPI 3.0 定义转换为 HTML 文档，然后使用浏览器的“保存为 PDF”功能将 HTML 转换为 PDF。

按照以下步骤操作：

转到https://editor.swagger.io。
粘贴您的 OpenAPI 3.0 YAML/JSON 定义。
选择生成客户端> html。
下载并解压缩文件。
在浏览器中打开index.html 页面，例如铬。
选择File > Print，将Destination更改为Save as PDF，然后保存页面。

【讨论】：

仅供参考，'openapi-generator-gradle-plugin' 使得步骤 1 到 4 包括多余的。