Question

如何将URL链接添加到我的swagger API（引用本地主机）？我不想在文件中添加硬编码的URL，因为该URL在每个环境中都会有所不同。尝试以下方法（指定localhost）无效。

externalDocs:
  description: "View application metrics"
  url: "http://localhost:3001/metrics"

Answer 1

OpenAPI 3.0（openapi: 3.0.0）支持相对的externalDocs URL，但OpenAPI 2.0（swagger: '2.0'）不支持。

假设您使用的是OpenAPI 3.0，并且您的OpenAPI文件托管在http://localhost:3001/openapi.yaml上，则可以使用：

openapi: 3.0.0
...

externalDocs:
  description: View application metrics
  url: /metrics     # <--- http://localhost:3001/metrics

注意：如果您的API定义包括servers，则会根据servers而不是OpenAPI文件的位置来解析相对URL。

openapi: 3.0.0
...

servers:
  - url: 'https://api.example.com/v1'

externalDocs:
  description: View application metrics
  url: /metrics    # <--- https://api.example.com/metrics

更多信息：API Host and Base Path

Answer 2

您可以按照以下步骤操作：

在json中转换yaml
更改主机并保存
再次将保存的json转换为yaml

大张旗鼓地将json文件用作文档，因此您可能不需要第三步。

const path = require("path");
const yaml = require("js-yaml");
const fs = require("fs");

const host = "127.0.0.1:3000"; // any host
const doc = yaml.safeLoad(fs.readFileSync("swagger.yaml"));
doc.host = host;
fs.writeFileSync(
  path.join("swagger_new.json"),
  JSON.stringify(doc, null, "  ")
);

希望有帮助！

Swagger YAML文件添加动态URL

2 个答案: