Ubuntu 14.04 - Installing Swagger 2.0

Update 14th March 2019

This post is very old now and I would recommend using this instead.

Introduction

Swagger is an opensource project that aims to simplify the documentation of one's RESTful APIs. Documenting one's API can be done in JSON or YAML and can lead to practicing true REST practices, such as returning error codes, and not just using GET/POST for all requests.

There are two main parts, the Swagger Editor and the Swagger UI. The editor helps one to create the swagger configuration file that represents the API. This file can then be loaded by other developers with the UI in order to read about the API.

Swagger supports advanced features such as inheritance and composition, but it can be hard to find examples of these online, and they are not yet fully supported by the UI tool.

Ihttpnstalling Swagger Editor

sudo apt-get install nodejs-legacy
git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm start

Swagger UI

The easiest way to deploy swagger UI is through docker. The following code will download the latest release from the releases page at the time of this writing, however you may need to check it and alter the wget and extraction lines accordingly.

wget https://github.com/swagger-api/swagger-ui/archive/v2.1.4.tar.gz
tar --extract --gzip --file v2.1.4.tar.gz
cd swagger*
docker build -t swagger-ui-builder .

Once that has finished building, you want to run the container you just generated. The following instruction will run the container so that people will view the documentation on the default port of 80 so that visitors will not have to enter a port number.

docker run -p 80:8080 \
swagger-ui-builder

Please note that the default code will simply display the petstore example and allow you to load a link to your JSON file. You probably don't want to do this and want to just display the specification you have generated. To do this, you need to edit the dist/index.html file as described here with this example. You basically add a new variable called spec which is your JSON document, and refer to it later when setting the window.swaggerUi as shown in the code snippet below:

...
window.swaggerUi = new SwaggerUi({
        url: url,
        spec: spec,
        dom_id: "swagger-ui-container",
...

Conclusion

You can now get started with playing around in swagger. In later tutorials we will cover how to use the editor to create a config file whilst making use of features such as object composition and inheritance. We will also cover the extra steps you need to take so that external UIs (different domain) can make use of your config through CORBA requests.

References

• Github - Swagger Editor
• Stack Overflow -Can not install packages using node package manager in Ubuntu