How to set up multiple swagger specs in swagger UI

Swagger UI is one of the best and easiest API documentation rendering tools. With swagger UI docker, we can quickly set up an API documentation page for API defined using swagger specifications.

Note: If you just need multiple spec support, jump the next two sections.

Docker command line

Assume, we have a swagger spec file allAPI-swagger.json located in the folder /home/chetansk/Desktop. To serve the API documentation on port 81 just run the below command. You could replace spec file, folder and port number below to adopt your environment

docker run -p 81:8080 -e SWAGGER_JSON=/foo/allAPI-swagger.json -v /home/chetansk/Desktop/:/foo swaggerapi/swagger-ui

Using docker-compose

We can also create a docker-compose file, the file for above command looks something like this

version: '3'
services:
        swagger-ui:
                ports:
                        - 81:8080
                image: swaggerapi/swagger-ui
                restart: always
                volumes:
                        - /home/chetansk/Desktop:/foo
                environment:
                        SWAGGER_JSON: /foo/allAPI-swagger.json

Multiple specs

It is often common to have multiple swagger specs, each one for a microservice, let us start with two swagger specs as aicon_um-swagger.json, and aicon_dm-swagger.json. We also assume these files represents two microservice — user management and device management

We need to add these specs to the docker environment URLS as below. Note the “ is escaped using a \

URLS="[{ url: \"./myfiles/aicon_um-swagger.json\", name: \"UserManagement\" },{url: \"./myfiles/aicon_dm-swagger.json\", name: \"DeviceManagement\"} ]"

A docker CLI to render multiple specs is as follows

docker run -p 81:8080 -e URLS="[{ url: \"./myfiles/aicon_um-swagger.json\", name: \"UserManagement\" },{url: \"./myfiles/aicon_dm-swagger.json\", name: \"DeviceManagement\"} ]"   -v /home/chetansk/Desktop/:/usr/share/nginx/html/myfiles swaggerapi/swagger-ui

A docker-compose file for the same CLI above looks like this

version: '3'
services:
    swagger-ui:
        ports:
          - 8080:8080
        image: swaggerapi/swagger-ui
        restart: always
        volumes:
          - .:/usr/share/nginx/html/api
        environment:
                URLS: "[{ url: \"./api/aicon_um-swagger.json\", name: \"UserManagement\" },
                        { url: \"./api/aicon_dm-swagger.json\", name: \"DeviceManagement\" },
                       ]"