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.
Continue reading →