如何从 OpenAPI 3.0 生成 PDF 或标记?

Posted

技术标签:

【中文标题】如何从 OpenAPI 3.0 生成 PDF 或标记?【英文标题】:How to generate a PDF or markup from OpenAPI 3.0? 【发布时间】: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 【参考方案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 包括多余的。

以上是关于如何从 OpenAPI 3.0 生成 PDF 或标记?的主要内容,如果未能解决你的问题,请参考以下文章

Java - 如何直接从 openapi 3.0 规范生成 Swagger UI

如何使用 Springdoc 在 OpenAPI 3.0 中创建链接?

如何在 Gradle 中为 OpenAPI 3.0 使用 Swagger Codegen?

有没有办法在 OpenAPI 3.0 中描述两种不同的响应类型?

如何在OpenAPI 3.0中用两个可选参数定义路径?

如何从 openapi 生成器编译一个在生成的源文件夹中实现接口的项目?