如何从 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?