As part of my work I had to get acquainted with Swagger and found that, while there is a lot of documentation it seems a bit difficult to find the right starting point.
A few things to consider before getting started:
- If you are situated behind a corporate firewall which prevents maven from working, I heavily suggest downloading the dependencies using maven in some private network and then referring to the local copy of the dependencies using mavens local repository capabilities.
To begin with a short summary on what Swagger actually is:
Technically speaking – Swagger is a formal specification surrounded by a large ecosystem of tools, which includes everything from front-end user interfaces, low-level code libraries and commercial API management solutions.
Quoted from http://swagger.io/getting-started/
There are two sides of Swagger, “the front” and “the back”. The back, would be an API provider which wants to use Swagger to describe APIs and the front is an API consumer who would like to get some client code to integrate with a provided API.
In both cases Swagger has a solution, both are described in the “Getting Started guide“.
Now one of the things I found lacking was an actual description of the different parts of swagger seperated into git repositories, which is why I will list them here:
Swagger Core
As the name implies Swagger Core is an implementation of the Swagger Spec in Java. It currently has an integration with JAX-RS and generates a Swagger compliant Json which can be used for the Swagger UI.
The corresponding core repositories for other languages are:
Swagger js – for Javascript
swagger-node – for Node.js
Swagger Spec
Contains the Swagger Specification, if one wants to have a look at examples of how the swagger api should look like, they should look into here. On the webpage this information described in this repository is nicely formatted and provides a good reference.
Swagger UI
This repository contains the information and source needed to generate a UI as shown inn the live demo. It takes in a Swagger API compliant Json and generates the UI using either the default look or a customised one. The default can be useed without needing to build the repo, but the custom one needs some copilations, which are described on the git repo.
Swagger Codegen
Provides an engine which can create client code from Swagger Spec compliant data.
Swagger Editor
Provides a browser based editor in which Swagger definitions can be created.
The remaining repositories are validator-badge, swagger-tools and swagger-parser, which are useful utilities.
Setup tutorial
There are two ways to get the required libraries for Swagger, one can either build the jars by cloning the git repository (https://github.com/swagger-api/swagger-core.git) and running mvn -N (after the first run mvn install). Or by downloading the required jars from the maven central.
If you decide to download the required jars you will need:
swagger-annotations, swagger-core, swagger-hibernate-validations, swagger-jaxrs, swagger-jersey2-jaxrs, swagger-jersey-jaxrs, swagger-models, swagger-mule and swagger-servlet.
Note: The versions have to match.
Once we have the required libraries we can download the samples to experiment. While some links still point to the swagger-core library for the samples the actually moved to their own repository: https://github.com/swagger-api/swagger-samples
In case you prefer a step by step guide the documentation of swagger-core provides instructions on setting up a basic swagger project, given a simple working REST webservice/webapp.
Personally I recommend having a look at the swagger-samples to get a feel for Swagger, each of the samples has a README file with instructions on how they are to be run.
To understand the behaviour of the annotations in swagger one should read the documentation here. This doc describes which annotations are essential for the doc generation and which are optional.
About Me, Tech and anything else 