Question

I have an OpenAPI 3.0 spec and I want to generate a PDF out of it so that it can be given to the end users.

Currently, tools like swagger-spec-to-pdf or swagger2markup only support Swagger 2.0 but not OpenAPI 3.0. Is it possible to generate a PDF from an OpenAPI 3.0 spec without converting it to Swagger 2.0?

Answer 1

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

请按照以下步骤操作：

转到http://editor.swagger.io。
粘贴您的OpenAPI 3.0 YAML / JSON定义。
选择 Generate Client> html 。
下载并解压缩文件。
在浏览器中打开index.html页面，例如Chrome。
选择文件>打印，将目标更改为另存为PDF ，然后保存页面。

Answer 2

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

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

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

Answer 3

以下是工具列表：

https://openapi.tools/#documentation

但是我还没有尝试全部/找到一个看起来不错的PDF和HTML5并可以通过命令行调用。

Answer 4

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

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

应用相关的 Plugin 类，其余的都是非常简单的任务配置。这是我的常规插件，但如果需要，找到对应的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
}

请告诉我有关此代码段的问题（或其中的语法错误）。

Answer 5

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

How to generate a PDF or markup from OpenAPI 3.0?

5 个答案: