如何运行 swagger-ui 本地代码更改和我自己的 swagger.json？

Question

https://github.com/swagger-api/swagger-ui 上的自述文件指定 Swagger-UI 可以运行与您自己的文件这样

docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui

如果我把它翻译成

docker build . -t swagger-ui-local && \
  docker run -p 80:8080 -e SWAGGER_JSON=/foo/my-file.json -v $PWD:/foo swagger-ui-local

但是，这会忽略我的本地更改。

我可以运行我的本地更改

npm run dev

但是除了 Petstore 示例之外，我不知道如何让这个开发服务器运行任何其他东西。

任何人都可以帮助我将两者结合起来，这样我就可以运行 swagger-ui 本地代码更改和我自己的 swagger.json?

Answer 1

我想出了 npm run dev:

将 my-file.json 放入 dev-helpers 文件夹。然后可以从 http://localhost:3200/.

的搜索栏中找到它

要在打开服务器时自动加载它，请通过更改

来更改dev-helpers/index.html

url: "http://petstore.swagger.io/v2/swagger.json"

到

url: "my-file.json"

Answer 2

以防万一您运行使用 Play Framework 创建 Maven 项目，以下步骤解决了我的问题：

1.) 修改 conf/routes 文件。添加以下行： GET /swagger.json controllers.Assets.at(path="/public/swagger-ui",file="swagger.json")

2.) 将 swagger.json 文件添加到您的 Swagger-UI 文件夹

所以当你运行端口示例7777中的mvn项目，使用mvn play2:run启动播放服务器然后，localhost:7777/docs会自动拉取Json 本地添加的文件。

Answer 3

确保您正在卷挂载正确的本地目录。

在本地，我在 $PWD/src/app/swagger/swagger.yaml 中进行了 swagger 配置。运行以下工作正常：

docker run -p 80:8080 -e SWAGGER_JSON=/tmp/swagger.yaml -v `pwd`/src/app/swagger:/tmp swaggerapi/swagger-ui

只需刷新 Swagger-UI 页面或单击 header 中的“浏览”按钮即可触发刷新我的 YAML 文件中的数据。

您还可以指定 BASE_URL 摘自 swagger-installation

docker run -p 80:8080 -e BASE_URL=/swagger -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui

Answer 4

我找到这个主题是因为我想查看本地 swagger 文件的可视化表示，但似乎无法获得 swagger-ui（运行 in docker）显示宠物店以外的任何内容。

最终，我的问题是理解 -e SWAGGER_JSON 和 -v 标志，所以我想在这里解释一下。

-v <path1>:<path2>

这个选项表示 "Mount the path <path1> from my local file system within the swagger-ui docker container on path <path2>"

-e SWAGGER_JSON=<filepath>

这个选项说 "By default, show the swagger for the file at <filepath> using the docker container's file system." 这里的重要部分是这个文件路径应该考虑到你如何设置上面的

综合起来，我得到了以下结果：

docker run -p 8085:8080 -e SWAGGER_JSON=/foo/swagger.json -v `pwd`:/foo swaggerapi/swagger-ui

这是英文的："Run my swagger-ui instance on port 8085. Mount my current working directory as '/foo' in the docker container. By default, show the swagger file at '/foo/swagger.json'."

需要注意的重要一点是，我的当前工作目录中有一个名为 swagger.json 的文件。此命令将我当前的工作目录挂载为 docker 容器中的 /foo。然后，大摇大摆的UI可以把我的swagger.json捡起来当/foo/swagger.json.

Answer 5

这是我最终解决这个问题的方法，它还允许您拥有多个 YML 文件：

docker run -p 80:8080 \                                                                                                                                 
  -e URLS_PRIMARY_NAME=FIRST \                                                                                                                             
  -e URLS="[ \                                                                                                                                           
    { url: 'docs/first.yml', name: 'FIRST' } \                                                                                                               
    , { url: 'docs/second.yml', name: 'SECOND' } \                                                                                                             
  ]" \                                                                                                                                                   
  -v `pwd`:/usr/share/nginx/html/docs/ \                                                                                                                 
  swaggerapi/swagger-ui

Answer 6

Docker 编写解决方案：

创建 .env 文件并添加以下内容：

URLS_PRIMARY_NAME=FIRST
URLS=[ { url: 'docs/swagger.yaml', name: 'FIRST' } ]

并创建一个 docker-compose 文件，内容如下：

version: "3.3"

services:
 swagger-ui:
  image: swaggerapi/swagger-ui
  container_name: "swagger-ui"
  ports:
    - "80:8080"
  volumes:
   - /local/tmp:/usr/share/nginx/html/docs/
  environment:
    - URLS_PRIMARY_NAME=${URLS_PRIMARY_NAME}
    - URLS=${URLS}

swagger.yaml 在 /local/tmp。

Answer 7

对于 mac 中遇到此问题的人来说，这是一个权限问题。在 Catalina 之后默认情况下，docker 没有权限允许其图像读取您系统中的本地文件。一旦给出它对我有用，它就占用了我当地的 swagger json 文件。

现在要授予权限，请转到系统偏好设置> 安全和隐私> 文件和文件夹，然后为 Mac 和您的共享目录添加 Docker。

Answer 8

如果您想提供多个 URL 并来自特定文件夹（非默认 /usr/share/nginx/html/docs/）的另一种解决方案：

docker run -p 80:8080 \
    -e SWAGGER_JSON=/docs/api.yaml \
    -e URLS="[ \
        { url: '/api1.yaml', name: 'API 1' }, \
        { url: '/api2.yaml', name: 'API 2' } \
    ]" \
    -v `pwd`/docs:/docs \
    swaggerapi/swagger-ui

或 docker 撰写：

version: '3.8'
services:
  swagger-ui:
    image: swaggerapi/swagger-ui
    volumes:
      - ./docs:/docs
    environment:
      SWAGGER_JSON: /docs/api.yaml
      URLS: '[{ url: "/api1.yaml", name: "API 1" }, { url: "/api2.yaml", name: "API 2" }]'

请注意，SWAGGER_JSON 需要绝对路径，URLS 中的 URL 需要来自指定卷的相对路径

如何 运行 swagger-ui 本地代码更改和我自己的 swagger.json？

How to run swagger-ui with local code changes AND my own swagger.json?

npm

swagger

docker

swagger-ui

如何运行 swagger-ui 本地代码更改和我自己的 swagger.json？