创建包含Swagger JSON

Question

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

所以我downloaded最新的标签v2.1.8-M1并解压缩了。然后我进入子文件夹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

Answer 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，然后点击“探索”

Answer 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, saute 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 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文件，我复制到下面的路径：
```
./swagger-editor/api/swagger/swagger.json
```
所有设置完成后，使用以下命令运行swagger-edit
```
npm install
npm run build
npm start
```
系统会提示您输入2个网址，其中一个网址可能如下：
```
http://127.0.0.1:3001/
```
以上是swagger-editor URL
现在浏览到：
```
http://127.0.0.1:3001/swagger-ui/dist/
```
以上是swagger-ui网址

多数人。

您现在可以浏览任何一个文件 swagger-ui或招摇编辑器

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

我花了大约2天的时间进行斗争，一次性安装只花了大约5分钟。

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

Answer 4

什么有效，是在不使用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并且正常工作

<强> HINT

这个答案适用于Win7上的Firefox。对于Chrome浏览器，请参阅以下评论：

Answer 5

我设法使用以下 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 文件加载 swagger 规范

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

Answer 6

如果您只想在swagger用户界面中查看swagger文档文件（例如swagger.json），请尝试open-swagger-ui（本质上是在swagger ui中打开）。

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

Answer 7

我有这个问题，这是一个更简单的解决方案：

在公共目录中制作一个目录（例如：swagger-ui）（静态路径：无路径是必需的）并将dist从swagger-ui复制到该目录中打开 localhost / swagger-ui
您将看到带有默认petstore示例的swagger-ui
使用 localhost / api-docs 替换dist / index.html中的默认petstore网址，或者将其更加通用化，替换为：

location.protocol +＆＃39; //＆＃39; + location.hostname +（location.port？＆＃39;：＆＃39; + location.port：＆＃39;＆＃39;）+＆＃34; / api-docs＆＃34;; < / p>
再次点击 localhost / swagger-ui

瞧！你本地的swagger实现准备就绪了

Answer 8

我的环境，
Firefox 45.9， Windows 7
swagger-ui ie 3.x

我做了解压缩，而且petstore在Firefox标签中出现了。然后我打开了一个新的Firefox选项卡，然后转到File＆gt;打开文件并打开我的swagger.json文件。该文件清晰，即作为文件。

然后我复制了文件位置＆＃39;来自Firefox（即URL位置，例如：file：/// D：/My%20Applications/Swagger/swagger-ui-master/dist/MySwagger.json）。

然后我回到了swagger UI选项卡并将文件位置文本粘贴到swagger UI浏览窗口中，我的招摇就变得干净了。

希望这会有所帮助。

Answer 9

<强> LINUX

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

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

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

cd /path/to/your/swaggerui where index.html is
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
}

Answer 10

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

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

Answer 12

可以选择使用 redoc。

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

Answer 13

这不是一个答案，只是 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>

Answer 14

使用Firefox，我：

Downloaded并将Swagger.IO的版本解压缩到C：\ Swagger \
在C：\ Swagger \ dist

Definitions

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

小心你的斜线指示!!

看起来你可以在文件夹结构中向下钻取，但不要兴奋。

Answer 15

另一个选择是使用docker运行swagger，你可以使用这个docker image：

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

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

for s in los:
    if s in self.__dict__:
        del self.__dict__[s]

Answer 16

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

希望这适合你

Answer 17

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

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

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

17 个答案:

创建包含Swagger JSON

修改Swagger UI index.html

包括spec.js

添加规范参数