如何在 Swagger-UI 中打开本地文件

Posted 2023-02-16

技术标签:

【中文标题】如何在 Swagger-UI 中打开本地文件【英文标题】：How to open local files in Swagger-UI 【发布时间】：2015-08-04 16:47:21 【问题描述】：

我正在尝试在我的本地计算机上用swagger-ui 打开我自己生成的swagger 规范文件my.json。

所以我downloaded 最新标签 v2.1.8-M1 并解压缩了 zip。然后我进入子文件夹dist 并将文件my.json 复制到其中。现在我打开了index.html，想探索my.json。问题从这里开始：

如果我输入本地路径，它将始终以包含index.html 的当前 url 为前缀。因此我无法打开我的文件。我尝试了以下所有组合但均未成功：

my.json 导致file:///D:/swagger-ui/dist/index.html/my.json file:///D:/swagger-ui/dist/my.json 导致file:///D:/swagger-ui/dist/index.html/file:///D:/swagger-ui/dist/my.json

【问题讨论】：

您实际上不需要托管您的 Swagger UI 来查看 Swagger 规范。我写了一篇文章，解释了如何使用在线可用的 petstore Swagger UI 来查看你的 swagger 规范。看看这个 - medium.com/@requestly_ext/… 【参考方案1】：

我无法得到 Adam Taras 的答案（即使用相对路径 ../my.json）。

这是我的解决方案（如果您安装了节点，非常快速且轻松）：

使用 Node，全局安装包 http-server npm install -g http-server 将目录更改为 my.json 所在的位置，然后运行命令 http-server --cors（必须启用 CORS 才能工作）打开 swagger ui（即 dist/index.html）在输入框中输入http://localhost:8080/my.json，然后点击“探索”

【讨论】：

这是一个糟糕的设计。为什么不让 Swagger UI 在本地节点服务器上运行？ @KennyWorden，因为那行不通-也许下次测试？在本地节点服务器上托管 Swagger UI 工作正常，但是如果我输入 API 的本地路径，即“file:///path/to/api.json”，UI 会自动附加“localhost:8080/file:///path/to/api.json” - 显然这条路行不通。我可以将 API 移动到同一个目录，输入“my.json”，但是将 API 复制到 Swagger UI 位置也不一定是“漂亮的”——任何变体都是丑陋的。这可能会让您个人感觉更好，但我宁愿少一些可靠工作的步骤。谢谢。这正是我所缺少的。 --cors 参数。我将它与完美连接到 http-server 的 docker 映像一起使用。再次感谢。嗯，这是一个关于 http 服务器如何工作的速成课程，但我设法让它全部运行起来。谢谢！推荐http-server --cors -a 127.0.0.1 以防止网络上的其他人浏览您的目录索引。【参考方案2】：

使用spec parameter。

以下说明。

创建包含 Swagger JSON 的 spec.js 文件

在与 index.html (/dist/) 相同的目录中创建一个新的 javascript 文件

然后插入spec变量声明：

var spec =

然后粘贴到swagger.json文件内容之后。它不必与= 符号在同一行。

例子：

var spec =


    "swagger": "2.0",
    "info": 
        "title": "I love Tex-Mex API",
        "description": "You can barbecue it, boil it, broil it, bake it, sauté it. Dey's uh, Tex-Mex-kabobs, Tex-Mex creole, Tex-Mex gumbo. Pan fried, deep fried, stir-fried. There's pineapple Tex-Mex, lemon Tex-Mex, coconut Tex-Mex, pepper Tex-Mex, Tex-Mex soup, Tex-Mex stew, Tex-Mex salad, Tex-Mex and potatoes, Tex-Mex burger, Tex-Mex sandwich..",
        "version": "1.0.0"
    ,
    ...

修改 Swagger UI index.html

这是一个像 Ciara 一样的两步。

包含 spec.js

修改 /dist/index.html 文件以包含外部 spec.js 文件。

 <script src='spec.js' type="text/javascript"></script>

例子：

  <!-- Some basic translations -->
  <!-- <script src='lang/translator.js' type='text/javascript'></script> -->
  <!-- <script src='lang/ru.js' type='text/javascript'></script> -->
  <!-- <script src='lang/en.js' type='text/javascript'></script> -->

  <!-- Original file pauses -->
  <!-- Insert external modified swagger.json -->
  <script src='spec.js' type="text/javascript"></script>
  <!-- Original file resumes -->

  <script type="text/javascript">

    $(function () 
      var url = window.location.search.match(/url=([^&]+)/);
      if (url && url.length > 1) 
        url = decodeURIComponent(url[1]);
       else 
        url = "http://petstore.swagger.io/v2/swagger.json";

添加规格参数

修改 SwaggerUi 实例以包含 spec 参数：

  window.swaggerUi = new SwaggerUi(
    url: url,
    spec: spec,
    dom_id: "swagger-ui-container",

【讨论】：

这给出了以下错误：已完成加载资源信息。渲染 Swagger UI... 这可以很好地工作，而不必与npm 混淆，并保持在本地托管dist/ 文件夹的能力，这是重点。 2021 年 1 月仍在工作，swagger 3.38.0【参考方案3】：

经过一番挣扎，我找到了更好的解决方案。

创建一个名为：swagger 的目录

mkdir C:\swagger

如果您在 Linux 中，请尝试：

    mkdir /opt/swagger

使用以下命令获取 swagger-editor：

git clone https://github.com/swagger-api/swagger-editor.git

进入现在创建的 swagger-editor 目录

cd swagger-editor

现在使用以下命令获取 swagger-ui：

git clone https://github.com/swagger-api/swagger-ui.git

现在，复制你的招摇文件，我复制到以下路径：

./swagger-editor/api/swagger/swagger.json

所有设置完成，使用以下命令运行 swagger-edit

npm install
npm run build
npm start

系统将提示您 2 个 URL，其中一个可能如下所示：

http://127.0.0.1:3001/

上面是swagger-editor URL

现在浏览到：

http://127.0.0.1:3001/swagger-ui/dist/

上面是swagger-ui URL

就是这样。

您现在可以从任一浏览文件 swagger-ui 或大摇大摆的编辑器

安装/构建需要时间，但一旦完成，您会看到很好的结果。

我折腾了大概2天，一次安装只用了5分钟左右。

现在，您可以在右上角浏览到本地文件。

祝你好运。

【讨论】：

谢谢。只是一个注释。由于我们在这个场景下运行在nodejs下，所以我们并没有真正从磁盘读取文件而是使用URL，例如：10.0.60.76:3001/swagger-ui/myfile.json（这个不是在浏览器的URL中输入，而是在打开的文件中）浏览按钮左侧，然后单击浏览）。但我想大多数人只想在 swagger 网站上使用 swagger-ui，然后在他们的计算机上打开一个磁盘文件（这不会是一个 URL）。 127.0.0.1:3001/swagger-ui/dist 只是给了我很多重定向，直到它失败。 127.0.0.1:3001/swagger-ui/dist/index.html 有效，我需要将 127.0.0.1:3001/swagger-ui/dist/api/swagger/swagger.json 粘贴到“探索”字段并单击“探索”按钮。【参考方案4】：

在包含您要查看的文件./docs/specs/openapi.yml 的本地目录中，您可以运行以下命令来启动容器并访问http://127.0.0.1:8246 的规范。

docker run -t -i -p 8246:8080 -e SWAGGER_JSON=/var/specs/openapi.yml -v $PWD/docs/specs:/var/specs swaggerapi/swagger-ui

【讨论】：

这对我也有用。你知道我们如何删除 swagger UI 中的顶部栏，使其不显示 swagger 文件的 URL 位置吗？对于 Windows 用户：将 $PWD 替换为 %cd% @Sakib 您需要扩展或修改 docker 映像才能做到这一点。有点涉及在评论中解释。【参考方案5】：

如果您只想在 swagger UI 中查看 swagger doc 文件（比如 swagger.json），请尝试 open-swagger-ui（本质上是在“swagger ui”中打开）。

open-swagger-ui ./swagger.json --open

【讨论】：

谢谢！如果您只想可视化您的 swagger.json 文件，这可能是最简单的选择【参考方案6】：

有效的方法是在没有file://-protocol 的情况下输入相对路径或绝对路径：

../my.json 通向 file:///D:/swagger-ui/dist/index.html/../my.json 并且有效 /D:/swagger-ui/dist/my.json 通向 file:///D:/swagger-ui/dist/my.json 并且有效

提示

此答案适用于 Win7 上的 Firefox。对于 Chrome 浏览器，请参见下面的 cmets：

【讨论】：

Chrome 需要使用 --allow-file-access-from-files 参数或 --disable-web-security 参数启动才能使此提示起作用。如何使用户不需要启用--alow-file-access。我将向多人发送一个 .zip 文件【参考方案7】：

我设法使用以下 Node.js 工具加载了本地 swagger.json 规范，这几乎不需要 5 分钟即可完成

swagger-ui-dist

express

按照以下步骤进行

swagger.json

.js

swagger-ui.js

const express = require('express')
const pathToSwaggerUi = require('swagger-ui-dist').absolutePath()
const app = express()

// this is will load swagger ui
app.use(express.static(pathToSwaggerUi))

// this will serve your swagger.json file using express
app.use(express.static(`$__dirname`))

// use port of your choice
app.listen(5000)

npm install express

npm install swagger-ui-dist

node swagger-ui.js

http://localhost/5000

http://localhost:5000/swagger.json

您可以使用文件夹名称、JSON 文件名、静态公用文件夹来服务swagger.json、端口来服务，以方便您使用

【讨论】：

【参考方案8】：

我遇到了这个问题，这里有一个更简单的解决方案：

在您的公共目录中创建一个目录（例如：swagger-ui）（静态路径：无路由是必需的）并将 dist 从 swagger-ui 复制到该目录和打开 localhost/swagger-ui 您将看到带有默认 petstore 示例的 swagger-ui

将 dist/index.html 中的默认 petstore url 替换为您的 localhost/api-docs 或使其更通用，替换为：

location.protocol+'//' + location.hostname+(location.port ? ':' + location.port: '') + "/api-docs";

再次点击localhost/swagger-ui

瞧！您的本地 swagger 实施已准备就绪

【讨论】：

【参考方案9】：

Linux

我在尝试路径和规范参数时总是遇到问题。

因此，我选择了在线解决方案，该解决方案将自动更新 Swagger 上的 JSON，而无需重新导入。

如果你使用 npm 来启动你的 swagger 编辑器，你应该为你的 json 文件添加一个符号链接。

cd /path/to/your/swaggerui 其中index.html 是。

ln -s /path/to/your/generated/swagger.json

您可能会遇到缓存问题。解决这个问题的快速方法是在我的网址末尾添加一个令牌......

window.onload = function() 

var noCache = Math.floor((Math.random() * 1000000) + 1);

// Build a system
const editor = SwaggerEditorBundle(
url: "http://localhost:3001/swagger.json?"+noCache,
  dom_id: '#swagger-editor',
  layout: 'StandaloneLayout',
  presets: [
    SwaggerEditorStandalonePreset
  ]
)

window.editor = editor

【讨论】：

另外，需要将SwaggerEditorBundle的url改成swagger.json文件的相对路径。【参考方案10】：

我的环境，火狐 45.9 , 视窗 7 swagger-ui 即 3.x

我解压缩了，宠物商店在 Firefox 选项卡中正常显示。然后我打开一个新的 Firefox 选项卡并转到文件 > 打开文件并打开我的 swagger.json 文件。该文件出现干净，即作为一个文件。

然后我从 Firefox 复制了“文件位置”（即 URL 位置，例如：file:///D:/My%20Applications/Swagger/swagger-ui-master/dist/MySwagger.json）。

然后我返回到 swagger UI 选项卡并将文件位置文本粘贴到 swagger UI 探索窗口中，然后我的 swagger 就干净了。

希望这会有所帮助。

【讨论】：

【参考方案11】：

而不是将 swagger ui 作为文件打开 - 你放入浏览器 file:///D:/swagger-ui/dist/index.html 你可以：创建支持浏览并指向 D:/swagger-ui 的 iis 虚拟目录

打开mmc，添加iis服务，展开默认网站添加虚拟目录，放别名：swagger-ui，物理路径：（你的路径...）D:/swagger-ui 在 mmc 的中间窗格中双击“目录浏览” 在右侧窗格中的 mmc 中单击“启用” 之后在浏览器中输入 url 以打开本地 swagger-ui http://localhost/swagger-ui/dist/ 现在，如果您将文件复制到 dist 文件夹中，您可以使用 ../my.json，或者您可以为示例创建单独的文件夹，例如 D:/swagger-ui/samples 并使用 ../samples/my.json 或 @ 987654322@

【讨论】：

【参考方案12】：

这就是我使用本地 swagger JSON 的方式

让 tomcat 在本地机器上运行下载 Swagger UI 应用程序并将其解压到 tomcat 的 /webapps/swagger 文件夹中将本地 swagger json 文件放入 tomcat 的 /webapps/swagger 文件夹中启动tomcat (/bin/sh startup.sh) 打开浏览器并导航到http://localhost:8080/swagger/ 在 Swagger Explore 测试框中键入您的 swagger json 文件，这应该会呈现 API。

希望这对你有用

【讨论】：

【参考方案13】：

使用 Firefox，我：

Definitions

swagger.json

探索

小心你的斜线方向！！

您似乎可以向下钻取文件夹结构，但不能向上钻取，这很烦人。

【讨论】：

【参考方案14】：

这不是一个答案，只是对 paragbaxi 答案的一点更新，所以请投票original 回答而不是这个

paragbaxi's 解决方案将在 2021 年发挥作用

这里是最新 openapi=3.0.2 的完整 index.html：

<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" />
    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
    <style>
      html
      
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      

      *,
      *:before,
      *:after
      
        box-sizing: inherit;
      

      body
      
        margin:0;
        background: #fafafa;
      
    </style>
  </head>

  <body>
    <div id="swagger-ui"></div>
    <script src='spec.js' type="text/javascript"></script>
    <script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
    <script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
    <script>
    window.onload = function() 
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle(
        spec: spec,
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      );
      // End Swagger UI call region

      window.ui = ui;
    ;
  </script>
  </body>
</html>

【讨论】：

这不是答案。简单地说明某人的答案仍然有效并不能使帖子成为回答。如果需要，请删除并重新发布为评论，你说得对。这不是答案。不幸的是，我没有足够的声誉来制作 cmets。我发布此内容的原因是 paragbaxi 的代码与我们在 index.html 的上一个（2021 年）布局中的代码不同。我花了一些时间来弄清楚应该在哪里改变。我想帮助任何面临同样情况的人。如果您仍然认为应该将其删除并作为评论发布，您能否将我的代码发布为评论，我将删除我的代码。（对我来说谁发布代码无关紧要）【参考方案15】：

可以选择使用redoc。

它有cli可以轻松bundle spec and ReDoc into zero-dependency HTML file 响应式界面和其他专业人士所以你可以只共享 html 文件，而不会弄乱网络服务器。当然，如果规格发生变化，它需要再次捆绑。

【讨论】：

【参考方案16】：

还有一个带有 Swagger UI 的官方 Docker 镜像，所以如果你使用 Docker，这可能是让它在本地运行的最简单方法。

DockerHub 上的图像（文档链接已损坏）：https://hub.docker.com/r/swaggerapi/swagger-ui

GitHub 上的文档： https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md#docker

如果您使用docker-compose，您可以修改以下示例配置：

swagger:
  image: swaggerapi/swagger-ui
  environment:
    - "SWAGGER_JSON=/app/docs/[name of your OpenAPI file]"
  volumes:
    - "./[relative path of your OpenAPI file]:/app/docs"
  ports:
    - "[port you want to assign to the container]:8080"

（是的，在撰写本文时我知道这是第 17 条答案，但之前的答案中没有提到这个 Docker 容器）

【讨论】：

【参考方案17】：

还有一个选择是使用 docker 运行 swagger，你可以使用这个 docker 镜像：

https://hub.docker.com/r/madscientist/swagger-ui/

我制作了这个 ghetto 小 BASH 脚本来杀死正在运行的容器并重建，所以基本上每次您对规范进行更改并想查看它时，只需运行该脚本即可。确保将应用程序的名称放在 APP_NAME 变量中

#!/bin/bash

# Replace my_app with your application name
APP_NAME="my_app"

# Clean up old containers and images
old_containers=$(docker ps -a | grep $APP_NAME | awk ' print $1 ')
old_images=$(docker images | grep $APP_NAME | awk ' print $3 ')

if [[ $old_containers ]];
    then
        echo "Stopping old containers: $old_containers"
        docker stop $old_containers
        echo "Removing old containers: $old_containers"
        docker rm $old_containers
fi

if [[ $old_images ]];
    then
        echo "Removing stale images"
        docker rmi $old_images
fi

# Create new image
echo "Creating new image for $APP_NAME"
docker build . -t $APP_NAME

# Run container
echo "Running container with image $APP_NAME"
docker run -d --name $APP_NAME -p 8888:8888 $APP_NAME
echo "Check out your swaggery goodness here:

http://localhost:8888/swagger-ui/?url=http://localhost:8888/swagger-ui/swagger.yaml"

【讨论】：

以上是关于如何在 Swagger-UI 中打开本地文件的主要内容，如果未能解决你的问题，请参考以下文章

将文本区域保存到本地服务器上的 HTML 文件

让接口测试成为合格的桥梁——本地搭建 Swagger-UI 环境搭建

win10家庭版没有本地组组策略编辑器怎么办

GTK3下如何将文本域绑定到本地文件夹以获取文本

从本地上传到服务器上，再下载下来打开就成了乱码。本地上传的文档没有问题。

如何把FTP中的文件复制到本地文件夹