Forum Discussion
[Edited. Originally required hosted JSON spec. Now uses simpler local file approach.]
So, I found that the docker approach was the easiest way to go. From what I've read, there are many different ways to get your API to show in a Swagger UI on your own server but I could never find one place with all the steps. I've pieced together ONE way to do it that worked for me. (I should note that I'm really only using Swagger for its documentation capabilities as I already have an API and a testing framework.)
Here is a complete set of instructions:
- Edit your API in SwaggerHub. Make that your canonical source of truth.
- Export a JSON file of your API. This file should get checked in with your own server's code base. (Remember, I'm only using this for documentation -- I won't be generating any real APIs from this.) Let's call this file api.json. Keept it up to date as you would any documentation.
- Install docker. I got the docker community edition (https://www.docker.com/get-docker). It's free. The process will require you to register. You will need to run this in your server environment.
- Install the docker swagger-ui image using the following command:
docker pull swaggerapi/swagger-ui
- Now you can run the Swagger UI with your specification using docker:
docker run -p 80:8080 -e "SWAGGER_JSON=/api.json" -v /actual/path/to/api.json:/api.json swaggerapi/swagger-ui
- You should now be able to hit port 80 wherever docker is running and see your API spec.
Note, for those of us unfamiliar with docker, the -v option can be confusing and the notes in github really threw me off. The path to api.json specified in the "SWAGGER_JSON=/api.json" assignment is not the actual path to api.json! The -v parameter will map the actual path to the path specified in SWAGGER_JSON. (Thanks ponelat !!)
--Ray
Thanks for posting your steps Ray!
From a quick look, you could skip the hosting of the swagger.json, if your spec was public on SwaggerHub...
docker run -p 80:8080 -e API_URL="https://api.swaggerhub.com/apis/ponelat/limoncello/1.0.0" swaggerapi/swagger-ui
> Note: api.swaggerhub.com, for the API and app.swaggerhub.com web UI.
See: https://app.swaggerhub.com/apis/swagger-hub/registry-api/1.0.45 for ways of getting your spec.
- RayRenteria7 years agoNew Contributor
Thanks for making the point that the JSON is also accessible directly from a published instance directly on SwaggerHub. I should have added that I'm not ready to publish it and I'd like to restrict who has access to the API docs by IP address. By self-hosting the JSON, I have much more control over that.
--Ray
- ponelat7 years agoStaff
Hey Ray, that's understandable.
For SWAGGER_JSON there is confusion around the `-v` flag of docker ( it stands for volume, and is a way to mount a filesystem/file ).
See this thread for more info https://github.com/swagger-api/swagger-ui/issues/3348
tl;dr...
docker run -p 80:8080 -e "SWAGGER_JSON=/swagger.json" -v /home/josh/swagger.json:/swagger.json swaggerapi/swagger-ui
Replace `/home/josh/swagger.json` with the path to your swagger.json on your server/laptop.
For private specs in SwaggerHub, you can access them with an APIKEY, but the Open Source swaggerui docker image doesn't have a mechanism for that (yet).
- RayRenteria7 years agoNew Contributor
Ah! Thanks for that! I've updated my instructions above to reflect your feedback. Thanks for your help!
--Ray
Related Content
Recent Discussions
- 8 days agokj20nt
- 16 days agoprogrammer_j