urls option from custom swagger-config.yaml ignored.

[pschichtel]

Q&A (please complete the following information)

• OS: Archlinux
• Browser: Firefox
• Version: 76
• Method of installation: Docker
• Swagger-UI version: 3.25.3
• Swagger/OpenAPI version: OpenAPI 3.0

Content & configuration

Swagger-UI configuration options: I tried both yaml and json:

---
urls:
  - name: Master API
    url: specs/master.yaml
  - name: Bot API
    url: specs/bot.yaml

{
    "urls": [
        {
            "name": "Master API",
            "url": "specs/master.yaml"
        },
        {
            "name": "Bot API",
            "url": "specs/bot.yaml"
        }
    ]
}

I looked at the swagger-config.yaml from this repository for reference.

Describe the bug you're encountering

I have a micro service system with various swagger-specified APIs. My goal was to create a dedicated application, that integrates all the swagger documentation. ron in IRC suggested to use the urls option to configure multuple spec URLs to be selected. So I pulled the swaggerapi/swagger-ui:v3.25.3 image, copied my files in specified the URLS environment variable. As expected: The swagger UI shows the first URL in the list by default and allows to switch between the URLs using a selection in the header. Because we have many APIs, I then tried to use a custom swagger-config.yaml by copying it into the container and specifying CONFIG_URL=swagger-config.yaml with the contents from above.

The UI seems to load the correct swagger-config.yaml (or .json) file, but it still shows the default petstore spec, apparently ignoring the provided urls option.

To reproduce...

Steps to reproduce the behavior:

1. Copy a swagger spec to /usr/share/nginx/html/specs/ inside the swaggerapi/swagger-ui:v3.25.3 image
2. Copy a swagger-config.yaml to /usr/share/nginx/html/swagger-config.yaml with the following content:

   ---
   urls:
     - name: Spec
       url: specs/<spec file name>
   

3. Add ENV CONFIG_URL=swagger-config.yaml to the Dockerfile (or set it while running the container)
4. Open the swagger UI in the browser

Expected behavior

I'd expect to see the spec from the configured URL

[pschichtel]

env output from within the container:

BASE_URL=/docs
SWAGGER_JSON=/app/swagger.json
HOSTNAME=268ca27a3b29
SHLVL=1
PORT=8080
HOME=/root
PKG_RELEASE=1
CONFIG_URL=swagger-config.yaml
TERM=xterm
NGINX_VERSION=1.17.10
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
NJS_VERSION=0.3.9
API_KEY=**None**
PWD=/

Generated SwaggerUIBundle call:

// Begin Swagger UI call region
const ui = SwaggerUIBundle({
  url: "https://petstore.swagger.io/v2/swagger.json",
  "dom_id": "#swagger-ui",
  deepLinking: true,
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUIBundle.plugins.DownloadUrl
  ],
  layout: "StandaloneLayout",
  configUrl: "swagger-config.yaml",
})


// End Swagger UI call region

[pschichtel]

Has there been any progress here?

[TechHoops]

Wondering if anyone has any suggestions to resolve this? Stuck with exact same issue

[tim-lai]

@pschichtel It appears that the documentation for the urls parameter for Docker is incorrect. This feature has not yet been implemented. Right now, you can only specify a single url, not an array of urls.

[tim-lai]

@pschichtel update.. looks like I was wrong with my earlier comment. Take a look at this: https://github.com/swagger-api/swagger-ui/pull/6465 , where you can specify URLS in the docker-compose .env file.

[tim-lai]

Hmm, reading this again, this does look like a bug. Where it works as a querystring but not as a env variable.

[pschichtel]

this is about the option from swagger-config.yaml getting ignored, not about query or env vars.

[gueuselambix]

Hitting the same issue here. We want to collect several API-specs in one swagger-ui. Adding them via env URLS works, but is not human readable, YAML configuration is way better for this.

[pschichtel]

I worked around this by customizing the container with a custom entrypoint, that reads the config and fills in the ENV as required.

Before that I had another look at the code and it seems to me as if the Topbar is simply rendering too early, since the config loading happens asynchronous while the rest of the initialization continues immediately, so the UI renders with defaults instead of the external config. I'd assume this could be fixed by either triggering another component render once the config has finished loading or by delaying the rendering until the config is loaded.

I don't have the time to get into the codebase and since my workaround is acceptable for us, but it would still be great to have this fixed.

[ngocketit]

Using CONFIG_URL works for me. Example Dockerfile:

FROM swaggerapi/swagger-ui:latest

COPY swagger/*.json /usr/share/nginx/html/
ENV CONFIG_URL ./swagger-config.json
CMD ["sh", "/usr/share/nginx/run.sh"]

And swagger-config.json:

{
  "urls": [
    {
      "url": "./service1-swagger.json",
      "name": "Service 1"
    },
    {
      "url": "./service2-swagger.json",
      "name": "Service 2"
    }
  ]
}

[pschichtel]

Ha... apparently the switch to JSON was all that is needed... So maybe some documentation is needed here, that Yaml is not supported for the config.

[pavelsr]

Just tested, seems like documentation is really outdated. swagger-config.yaml is not supported for now, only swagger-config.json

Also having /usr/share/nginx/html/swagger-config.json is not enough, need to set -e CONFIG_URL=/swagger-config.json additionally while docker run.

$ docker images --digests --filter "reference=swaggerapi/swagger-ui"
REPOSITORY              TAG       DIGEST                                                                    IMAGE ID       CREATED       SIZE
swaggerapi/swagger-ui   latest    sha256:8d3f30b936cf117f83c87379aadc7b7507735a3e899b1d8fcc38f8d0939eee77   ecb990ee92e8   4 weeks ago   101MB

[ajoga]

For too fast too furious readers like me, FYI swagger-config.yaml is actually still supported, likely because a once broken support was fixed in #7749

swagger-config.yaml:

---
defaultModelExpandDepth: 6
defaultModelsExpandDepth: 6

docker run --rm -p 8080:8080 -v "${PWD}:/local" -e SWAGGER_JSON=/local/myapispec.yml -e CONFIG_URL=swagger-config.yaml  swaggerapi/swagger-ui

[SezBulent]

For me it still doesn't work properly, in the case of a docker setup. Running like the following ( in the base image test:5.22 i just copy those test api specs, and nothing more ):

docker run --rm --name test -p 80:80 -e URLS='[{ url: "/test-api/index.yaml", name: "Test API"}, { url: "/test-api2/index.yaml", name: "Test API 2"}]' test:5.22 /bin/sh -c "chmod 777 /usr/share/nginx/html/ /etc/nginx/conf.d/ /etc/nginx/conf.d/default.conf /var/cache/nginx/ /var/run/ && nginx -g 'daemon off;'"

Will not enable at all the dropdown for the added specs, and instead will just show me the "petstore" example from the default "url" config. Reading the documentation is says something obscure about enabling the "Topbar" plugin, for which i can't find anything in the docs.

@tim-lai How exactly can we enable this in the docker setup, as the lack of more information in the docs is driving me nuts ( or maybe I am probably not understanding something? ).

[gueuselambix]

Hi @SezBulent we got this working using the default docker swaggerapi/swagger-ui:latest

We add a json file to the docker at /usr/share/nginx/html/swagger-config.json:

{
  "urls": [
    {
      "url": "https://api.example.com/api/v1/api-docs",
      "name": "Example API"
    },
    {
      "url": "http://localhost:8086/api/v1/api-docs",
      "name": "Example API (Local)"
    },
    {
      "url": "./specs/example.yml",
      "name": "Example API (hosted)"
    }
  ],
  "dom_id": "#swagger-ui",
  "validatorUrl": "https://validator.swagger.io/validator"
}

As you can see it contains remote, localhost and even hosted specs. The hosted specs can be injected at /usr/share/nginx/html/specs

You also need to reference the configuration via an environment variable:

CONFIG_URL=./swagger-config.json

This results in a dropdown top right:

Beware of CORS when you add remote specs to it. If you host the swagger-ui at api-doc.example.com

The request contains:

Origin: https://api-doc.example.com

The server MUST respond with:

Access-Control-Allow-Origin: https://api-doc.example.com

Otherwise your browser will block the requests.

[SezBulent]

hi @gueuselambix thank you for your help and suggestions. Unfortunately, even like this, with your suggested config, the dropdown it's still not visible.

Dockerfile:

FROM swaggerapi/swagger-ui:v5.24.0

COPY ./test-api/specs /usr/share/nginx/html/specs/test-api
COPY ./test-api2/specs /usr/share/nginx/html/specs/test-api2
COPY ./swagger-config.json /usr/share/nginx/html/

swagger-config.json:

{
  "urls": [
    {
      "url": "./specs/test-api/index.yaml",
      "name": "Test API"
    },
    {
      "url": "./specs/test-api2/index.yaml",
      "name": "Test API 2"
    }
  ],
  "dom_id": "#swagger-ui",
  "validatorUrl": "https://validator.swagger.io/validator"
}

And running the image as ( i tried to use SWAGGER_JSON instead of CONFIG_URL, but to no result ):

docker run --rm --name tst -p 80:80 -e CONFIG_URL='/usr/share/nginx/html/swagger-config.json' tst /bin/sh -c "chmod 777 /usr/share/nginx/html/ /etc/nginx/conf.d/ /etc/nginx/conf.d/default.conf /var/cache/nginx/ /var/run/ && nginx -g 'daemon off;'"

I saw a new update has been dropped today, but the docs still haven't been updated properly or even the dockerfile. @char0n @tim-lai @JonathanParrilla sorry for tagging you guys, but a input would be really helpful here.

EDIT:

I just noticed that the specs can be found if the path is written in the "explore" search bar ( e.g ./specs/test-api/index.yaml or ./specs/test-api2/index.yaml ), even without using SWAGGER_JSON, CONFIG_URL or URLS variables, but simply the dropdown just fails to appear for whatever reason.

[SezBulent]

any help here?