从命令行将 Swagger YAML 文件转换为 JSON

Posted 2023-02-26

【中文标题】从命令行将 Swagger YAML 文件转换为 JSON

【英文标题】：Converting a Swagger YAML file to JSON from the command line

【发布时间】：2016-04-16 10:53:18

【问题描述】：

我想从命令行将 Swagger YAML 文件转换为 JSON。计划是在 CI 作业期间使用此命令行。我在 google 上搜索并找到了许多解决方案，但其中大多数使用 Python 或 Ruby，我不想使用它们。例如：http://www.commandlinefu.com/commands/view/12218/convert-yaml-to-json

我想在不使用 Python 或 Ruby 的情况下执行此操作，并且 当您选择 File -> Download JSON

这意味着我希望空白填充为四个空格，如下所示：

    "swagger": "2.0",
    "info": 
        "title": "API TITLE",

我没有尝试过上面链接中的 Python 方法，但是 Ruby 方法使用两个空格空白填充。也许有办法控制它，但我不想在这个解决方案中使用 Ruby 或 Python。

我确信这个问题有很多“正确”的答案。我正在寻找最优雅、依赖最少的解决方案。理想情况下，生成的 JSON 文件与 editor.swagger.io 生成的 JSON 文件的差异应该是空的。

【参考方案1】：

我认为您正在寻找swagger-codegen（现为OpenApi-generator）功能：

跑步

swagger-codegen generate -i swagger.yaml -l swagger

会在同一位置放一个 swagger.json。

CI 更新： 如果你可以将它安装在你的构建机器上——对你有好处。 如果你不能 - github页面有一个指向带有nodejs服务器的docker镜像的链接可用（使用curl命令进行转换，如不同答案中建议的那样）。

Docker 更新： 如果您使用 Docker，请尝试 swaggerapi/swagger-codegen-cli，有一个 docker-compose 示例可能有助于 F*** 和 ckeeney 的一些答案。

关于 OpenApi 的更新：

这个问题是关于swagger的，而且有几年了。如果你刚开始使用 Swagger，你应该改用 OpenApi，如果你有现有的 swagger 文件，我建议migrating。

【讨论】：

我确实喜欢这个答案，但是 docker 镜像是一个非常严重的依赖项。应该有一种方法可以将 YAML 规范发送到 generator.swagger.io 指向的 POST 端点，该端点本身使用 swagger-codegen 但我不知道如何在 POST 正文中发送规范：-/

我刚刚做了一个 npm install -g swagger-codegen 并没有包含那个命令！当我安装 npm install -g swagger-codegen-cli 时，swagger-codegen-cli 可用。

安装脚本当前失败，因为使用 wget 或 curl 无法访问 central.maven.org。我只能从浏览器下载 jar 文件。顺便说一句，Java 依赖是一个很大的骗局。可惜没有支持版本 3 的普通 php/nodejs 工具。

当我尝试使用 swagger codegen 时，我从 brew 获得的版本不支持 swagger 输出格式。

我发现openapi-generator 支持我拥有的 OpenAPI 规范。 swagger-codegen 比较老，而且似乎也有一些错误。我相信openapi-generator 这些天应该总是首选。 @Liel 也许更新你的答案？

【参考方案2】：

swagger-codegen cli 接口

作为Liel has already pointed out，你可以运行

swagger-codegen generate -i swagger.yaml -l swagger

码头工人

如果你使用 Docker，那么我建议你试试swaggerapi/swagger-codegen-cli。

您可以使用 docker 使用以下命令生成 json 文件：

docker run -v ./docs:/docs swaggerapi/swagger-codegen-cli generate -i /docs/swagger.yaml -l swagger -o /docs

我喜欢设置一个docker-compose.yml 来“别名”这个命令以便于重用：

version: "2"
services:
  gen-swagger:
    volumes:
      - ./docs:/docs
    image: swaggerapi/swagger-codegen-cli
    command: generate -i /docs/swagger.yaml -l swagger -o /docs

现在我可以运行docker-compose run gen-swagger

【讨论】：

这是一个很好的答案——也许可以将其编辑到 Liel 的答案中以做出单一、全面的答案？

【参考方案3】：

使用yamljs:

yaml2json swagger.yaml -p -i4

此命令的输出与editor.swagger.io 的 JSON 输出相比产生了一个空差异。

这确实是我正在寻找的，但它带来了巨大的依赖（节点）。我希望有一些更轻，但同样优雅的东西。

【讨论】：

这种方式有一个严重的“弊端”：不翻译跨文件关系。示例：$ref: 'Pet.yaml' 应转换为 $ref: 'Pet.json'

【参考方案4】：

对于版本 swagger-codegen 3.0.4

使用

swagger-codegen generate -i my_yaml.yaml -l openapi

获取.json。

【参考方案5】：

您可以使用在线 swagger codegen 项目来执行此操作：

curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "
  \"spec\": 
" "https://generator.swagger.io/api/gen/clients/swagger-yaml"

将您的 swagger 定义的值放入 spec 对象中。您将获得一个链接，以 yaml 格式下载经过转换和验证的规范。

有关选项，请看这里：

http://generator.swagger.io/

【讨论】：

这正是我正在寻找的答案，但反过来：我想从 YAML 转换为 JSON。我假设我想使用 https://generator.swagger.io/api/gen/clients/swagger 并且可能使用 mimetime application/x-yaml ？为了论证，我尝试使用 JSON 文件并转换为 yaml，但您的命令行和 http://generator.swagger.io 上的 api-explorer 似乎都不喜欢 spec 字段。有关如何在 POST 正文中使用 spec 字段的任何确切命令行示例？我建议为此端点添加 default 值，以说明这一点...

生成器目前不支持，但可以。我已经打开了这个问题，你可以跟踪它的进度：github.com/swagger-api/swagger-codegen/issues/1903

【参考方案6】：

另一种将 swagger.yml 文件转换为 swagger.json 的可能性是一个名为 swagger-cli 的 NPM 包。

npm install -g swagger-cli

然后你可以将一个yml转换成json文件：

swagger-cli bundle -o api-spec.json api-spec.yml

【讨论】：

很好的答案，除了问题要求最低依赖关系。如果您已经是 Node 用户，那就太好了。否则，没有那么多。但是必须有一种方法可以从 Docker 映像中使用swagger-cli。

【参考方案7】：

我会使用https://openapi-generator.tech/

这是一个 npm 安装（我只是在本地使用它npm install @openapitools/openapi-generator-cli）然后

npx @openapitools/openapi-generator-cli generate -i source.yaml -g openapi -o outputdir

【参考方案8】：

对于 Kotlin 的 gradle，我在我的 build.gradle.kts 中写道：

import com.fasterxml.jackson.databind.JsonNode
import com.fasterxml.jackson.databind.ObjectMapper
import com.fasterxml.jackson.dataformat.yaml.YAMLFactory
import java.nio.file.Path

然后在诸如compileJavacode 之类的任务中进行转换：

val compileJava: Task by tasks.getting 
  val openApiDir = "$rootProject.projectDir/openapi"    
  val json: JsonNode? = ObjectMapper(YAMLFactory())
    .readTree(Path.of("$openApiDir/openapi.yaml").toFile())
  ObjectMapper().writerWithDefaultPrettyPrinter()
    .writeValue(Path.of("$openApiDir/openapi.json").toFile(), json)