Forum Discussion

parminder's avatar
parminder
Occasional Visitor
9 years ago
Solved

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
  • RayRenteria's avatar
    RayRenteria
    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

8 Replies

Sort By
  • fehguy's avatar
    fehguy
    Icon for Staff rankStaff
    9 years ago

    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