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

Question

我正在尝试在我的本地计算机上使用 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

Answer 1

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

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

Answer 2

不是将 swagger ui 作为文件打开，而是将其放入浏览器文件:///D:/swagger-ui/dist/index.html 你可以：创建允许浏览并指向 D:/swagger-ui

的 iis 虚拟目录

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

Answer 3

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

这是我的解决方案（漂亮的 quick，如果你安装了 node 则无痛）：

使用 Node，全局安装包 http-server npm install -g http-server
将目录更改为 my.json 所在的位置，然后运行命令 http-server --cors（必须启用 CORS 才能工作)
张扬ui（即dist/index.html）
在输入字段中键入 http://localhost:8080/my.json，然后单击 "Explore"

Answer 4

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

在您的 public 目录中创建一个目录（例如：swagger-ui）（静态路径：无路由是 required) 并将 dist 从 swagger-ui 复制到该目录中，然后打开 localhost/swagger-ui
您将看到带有默认宠物店示例的 swagger-ui
将 dist/index.html 中的默认宠物店 url 替换为您的 localhost/api-docs 或者为了使其更通用，替换为：

location.protocol+'//' + location.hostname+(location.port ? ':' + location.port: '') + "/ api-文档";
再打localhost/swagger-ui

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

Answer 5

使用 spec parameter.

说明如下。

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

在与 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",

Answer 6

这就是我如何使用 local swagger JSON

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

希望这对你有用

Answer 7

另一种选择是运行使用 docker 招摇过市，您可以使用此 docker 图片：

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

我制作了这个 ghetto little BASH 脚本来杀死运行ning 容器并重建，所以基本上每次你对你的规范进行更改并想要查看它时，只需运行剧本。确保将您的应用程序名称放入 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  }')
old_images=$(docker images | grep $APP_NAME | awk '{ print  }')

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"

Answer 8

我的环境，
火狐 45.9 , Windows7
大摇大摆-ui 即 3.x

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

然后我从 Firefox 复制了 'file location'（即 URL 位置，例如：file:///D:/My%20Applications/Swagger/swagger-ui-master/dist/MySwagger.json ).

然后我回到 swagger UI 选项卡并将文件位置文本粘贴到 swagger UI explore window 中，我的 swagger 就干净了。

希望这对您有所帮助。

Answer 9

LINUX

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

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

如果您使用 npm 启动 swagger 编辑器，您应该添加 json 文件的符号 link。

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

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

您可能会遇到缓存问题。解决这个问题的快速方法是在我的 url...

的末尾添加一个标记

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
}

Answer 10

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

创建一个目录，名称为：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 文件，我复制到以下路径：
```
./swagger-editor/api/swagger/swagger.json
```
所有设置已完成，运行使用以下命令进行 swagger-edit
```
npm install
npm run build
npm start
```
系统将提示您 2 URL 秒，其中一个可能如下所示：
```
http://127.0.0.1:3001/
```
以上是swagger-editorURL
现在浏览至：
```
http://127.0.0.1:3001/swagger-ui/dist/
```
以上招摇-uiURL

就这些了。

您现在可以通过以下任一方式浏览文件大摇大摆-ui 或大摇大摆的编辑器

install/build需要时间，但一旦完成，您会看到很好的结果。

我奋斗了大概2天，一次性安装只用了5分钟左右

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

祝你好运。

Answer 11

使用 Firefox，我：

Downloaded 并将 Swagger.IO 的一个版本解压到 C:\Swagger\
在 C:\Swagger\dist

Definitions

在那里复制了我的 swagger.json 定义文件，并且
在探索框中输入"Definitions/MyDef.swagger.json"

注意斜线方向！！

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

Answer 12

在包含您要查看的文件 ./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

Answer 13

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

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

Answer 14

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

swagger-ui-dist

express

按照以下步骤操作

根据您的选择创建一个文件夹并将您的规格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
运行使用命令 node swagger-ui.js
打开浏览器并点击 http://localhost:5000，这将加载 swagger ui，默认 URL 为 https://petstore.swagger.io/v2/swagger.json
现在将上面提到的默认 URL 替换为 http://localhost:5000/swagger.json 并单击“浏览”按钮，这将从本地 JSON 文件

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

Answer 15

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

解决方案在 2021 年非常有效

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

<!-- 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>

Answer 16

有一个使用 redoc 的选项。

它有 cli 可以轻松 bundle spec and ReDoc into zero-dependency HTML file
响应式界面
和其他专业人士所以你只能共享 html 文件，而不会弄乱网络服务器。但是当然需要重新捆绑以防规格更改。

Answer 17

还有一个带有 Swagger UI 的官方 Docker 图像，所以如果您使用 Docker，这可能是在本地将其获取到运行的最简单方法.

Image 在 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 图片）

Answer 18

最简单的方法

1/运行

npx open-swagger-ui <path or URL>

2/ 导航至 http://localhost:3355/

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

How to open local files in Swagger-UI

file

swagger

swagger-ui

swagger-2.0

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

修改 Swagger UI index.html

包括spec.js

添加规范参数