Forum Discussion

parminder's avatar
parminder
Occasional Visitor
8 years ago

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 bot...
fehguy's avatar
fehguy
Staff

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.

RayRenteria's avatar
RayRenteria
New Contributor
8 years ago

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

 

 

  • RayRenteria's avatar
    RayRenteria
    New Contributor
    8 years ago

    [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

    • ponelat's avatar
      ponelat
      Staff
      8 years ago

      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.

      • RayRenteria's avatar
        RayRenteria
        New Contributor
        8 years ago

        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