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\" },
]"