I also received your emails directly, so it appears that you're using SwaggerHub to develop the definitions. I'm assuming that you now want to host the swagger-ui based on your SwaggerHub-defined definitions.
The suggested flow would be as follows:
* Keep your definition in SwaggerHub as the "source of truth". When you want to make changes, you would do so here.
* Use the GitHub sync integration to push the swagger JSON or YAML to your GitHub. This would be your "public facing" UI repository.
* Add the swagger-ui-dist package to your GitHub repository from above
* Publish your GitHub repository (perhaps using GH-Pages or SwaggerHub webhooks) on change
That allows a good flow, where you can have one source of truth for the definition and control over how and where it's pushed for end-user consumption.
I'm building my API in swaggerhub and I exported a JSON file. I'd like to host that on my server.
I cloned the github swagger-ui project (https://github.com/swagger-api/swagger-ui) though I'm not sure why I need to do this if I'm just using the pre-built docker image.
While not explicitly mentioned in your documentation, it's clear that you require docker to be installed. I installed docker and created an account on docker hub. This is not a small step and seems to render the cloning step as unnecessary, no?
I then ran the commands specified in the swagger-ui github project:
docker pull swaggerapi/swagger-ui docker run -p 80:8080 swaggerapi/swagger-ui
I was successfully able to see the petstore example on localhost. (yay)
Then I ran the command that was supposed to let me see my own API configuration in the UI (minus the -v run option):
docker run -p 80:8080 -e "SWAGGER_JSON=/path/to/my/swagger.json" swaggerapi/swagger-ui
I still only see the petstore example. (boo)
What am I missing?
[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:
docker pull swaggerapi/swagger-ui
docker run -p 80:8080 -e "SWAGGER_JSON=/api.json" -v /actual/path/to/api.json:/api.json swaggerapi/swagger-ui
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 !!)
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.
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.
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
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).
Ah! Thanks for that! I've updated my instructions above to reflect your feedback. Thanks for your help!
Our next big focus is to make several improvements to our documentation capabilities, including enabling customization and allowing customers to CNAME to it.
Would you be interested in a quick call with me so I can understand your needs? I'd appreciate your time!