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

Question

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

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

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

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

score 67 · Accepted Answer

我无法得到 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字段中输入并单击“探索”

score 27 · Accepted Answer

使用规范参数。

说明如下。

创建包含 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",

score 16 · Accepted Answer

在包含./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

score 16 · Accepted Answer

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

创建一个名为：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/
```
以上是招摇编辑器网址
现在浏览到：
```
http://127.0.0.1:3001/swagger-ui/dist/
```
上面是swagger-ui URL

就这样。

您现在可以从 swagger-ui 或 swagger-editor 浏览文件

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

对我来说大约花了 2 天的时间，一次安装只花了大约 5 分钟。

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

祝你好运。

score 6 · Accepted Answer

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

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

score 4 · Accepted Answer

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 浏览器，请参阅以下评论：

score 4 · Accepted Answer

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

招摇-ui-dist

表示

请按照以下步骤操作

根据您的选择创建一个文件夹并将您的规范复制swagger.json到新创建的文件夹
.js在我的情况下，在新创建的同一个文件夹中创建一个带有扩展名的swagger-ui.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
使用命令运行 express 应用程序node swagger-ui.js
打开浏览器并点击http://localhost:5000，这将加载默认 URL 为https://petstore.swagger.io/v2/swagger.json的 swagger ui
现在将上面提到的默认 URL 替换为http://localhost:5000/swagger.json并单击 Explore 按钮，这将从本地 JSON 文件加载 swagger 规范

您可以根据自己的方便使用文件夹名称、JSON 文件名、静态公共文件夹服务swagger.json、端口服务

score 2 · Accepted Answer

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

在您的公共目录（静态路径：不需要路由）中创建一个目录（例如：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

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

score 2 · Accepted Answer

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
}

score 1 · Accepted Answer

我的环境，
Firefox 45.9，Windows 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 变得干净利落。

希望这可以帮助。

score 0 · Accepted Answer

有一个使用redoc的选项。

它有 cli 可以轻松地将规范和 ReDoc 捆绑到零依赖的 HTML 文件中
响应式界面
和其他专业人士因此您可以只共享 html 文件，而不会弄乱网络服务器。但当然，如果规格发生变化，它需要再次捆绑。

score 0 · Accepted Answer

无需将 swagger ui 作为文件打开 - 您将其放入浏览器 file:///D:/swagger-ui/dist/index.html 您可以：创建 iis 虚拟目录，该目录启用浏览并指向 D:/swagger-ui

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

score 0 · Accepted Answer

使用 Firefox，我：

将 Swagger.IO 版本下载并解压到 C:\Swagger\
在 C:\Swagger\dist 中创建了一个名为Definitions的文件夹
在那里复制了我的swagger.json定义文件，然后
在探索框中输入“Definitions/MyDef.swagger.json”

小心你的斜线方向！！

看起来你可以向下钻取文件夹结构，但不能向上钻取，这很烦人。

score 0 · Accepted Answer

这不是一个答案，只是对 paragbaxi 答案的一点更新，所以请投票赞成原始答案而不是这个

paragbaxi 的解决方案在 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>

score 0 · Accepted Answer

还有一个带有 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 容器）

score 0 · Accepted Answer

这就是我使用本地 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。

希望这对你有用

score -1 · Accepted Answer

另一种选择是使用 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"

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

17 回答 17

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

修改 Swagger UI index.html

包括 spec.js

添加规格参数

Related

Reference