cancel
Showing results for 
Search instead for 
Did you mean: 

Host swagger API documentation on my own server

Highlighted
Occasional Visitor

Host swagger API documentation on my own server

Hello,

I have created two pages which is available publicly. I want to host those pages on my own server.

I saw the documentation and github for swagger-ui and swagger-editor

I installed both of them on my local server and it is pointing to default petstore and when I make changes to it and it saves to my local browser only (seems it has local storage only), not server side (on my server).
 
I want to host my API documentation with swagger on my own server, can anyone suggest how to proceed?
 
Thanks,
Parminder Singh
8 REPLIES 8
Highlighted
Staff

Re: Host swagger API documentation on my own server

Hi,

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.

-----
Tony Tam
SmartBear VP of Swagger Products
Highlighted
New Contributor

Re: Host swagger API documentation on my own server

Hi,

 

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?

 

--Ray

 

 

Highlighted
New Contributor

Re: Host swagger API documentation on my own server

[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:

 

  1. Edit your API in SwaggerHub.  Make that your canonical source of truth.
  2. 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.
  3. 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.
  4. Install the docker swagger-ui image using the following command:
    docker pull swaggerapi/swagger-ui
  5. 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
  6. 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

Highlighted
Contributor

Re: Host swagger API documentation on my own server

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.

Highlighted
New Contributor

Re: Host swagger API documentation on my own server

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

 

Highlighted
Contributor

Re: Host swagger API documentation on my own server

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).

Highlighted
New Contributor

Re: Host swagger API documentation on my own server

Ah! Thanks for that! I've updated my instructions above to reflect your feedback.  Thanks for your help!

 

--Ray

Highlighted
Staff

Re: Host swagger API documentation on my own server

Hi Ray-

 

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!

 

Click here to schedule a time.

 

Thanks,

Fernando

 

New Here?
Join us and watch the welcome video:
Announcements
Top Kudoed Authors