Swagger Documentation

Swagger is a tool that provides Developers a way to describe RESTFul APIs. BFF projects will be documented with Swagger in order to provide a rich representation about the available APIs, what HTTP methods are supported, and what inputs as well as possible outputs are expected when requesting these endpoints.

Swager come with a tool called Swagger-UI, this tool help us to visualize how the APIs are documented, that means if some field is required or so, Swagger-UI is a open source project and you can find it in this repository:

https://github.com/swagger-api/swagger-ui

Swagger-UI

Inside this project we are provided with a Dockerfile that enables launching the Docker container and be able to see the Swagger documentation.

To work with Swagger UI you first need to run the following command to get an image on Docker.

 $ docker pull swaggerapi/swagger-ui

Next, you can list the Docker images running the command $ docker imagesand in the output the image with name swaggerapi/swagger-ui should be listed . Also, in the TAG column the version is listed and that should correspond to latest

Then, a container should be created; such container is an instance from above image. To do that the following command should be executed:

$docker run -d -p 5555:8080 swaggerapi/swagger-ui:latest

In order to check if the created container was correctly generated, you can see it by running docker ps and the terminal should list the following:

Next, to open up the Swagger-UI the following command should be executed:

$ open -a Safari.app http://$REG_IP:5555

Immediately, your browser will open and will show you the Swagger Web UI by default this application explore this URL http://petstore.swagger.io/v2/swagger.json by default that contains all the documentation of one API example that is structured with JSON. Swagger UI can work with two type of paths YAML or JSON for specifications that are hosted on a sever. For our work we will use JSON.

You can change the URL manually, before that you have to be sure that your addressbook-bff is running and verify that this path http://localhost:7777/api/v1/api-doc is working correctly at your browser, this will show you the JSON structure of your Swagger documentation.

Now if you write http://localhost:7777/api/v1/api-doc inside the input of Swagger UI you can see all that information displayed at Swagger UI in a way more friendly and interactive.

To avoid to copy and paste this URL could specify the URL that would be loaded by default at the moment to run at Docker your Swagger UI image. Before that you have to stop your container , remove it and remove your swagger UI image for this you have to run docker stop [containerId] , docker rm [containerId]and finally rundocker rmi [imageId].

Swagger actually has an issue on its last version at the moment to define the URL by default, it seems that it doesn't working well when you launch Swagger UI, for that reason we will use the version 3.0.8 that works correctly.

One time that you run the commands mentioned before you have to run this.

docker pull swaggerapi/swagger-ui:v3.0.8

As we mentioned our version to work is specified at the end of the command :v3.0.8

When you create this new container you have to specify the parameter API_URL with the value that you want to be loaded

docker run -d -p 9999:8080 --restart=always -e API_URL=http://localhost:7777/api/v1/api-doc swaggerapi/swagger-ui:v3.0.8

Once it is done run this on your browser and you will see http://192.168.131.100:9999 that swagger displays the exploration of the specified URL by default.

Swagger on AddressBook-Bff

In previous chapters of this tutorial we added dependencies to provide Swagger documentation through Camel as we can verify at the file pom.xml inside our project.

<dependency>

<groupId>org.apache.camel</groupId>

<artifactId>camel-swagger-java-starter</artifactId>

<version>2.18.1</version>

</dependency>

PersonRoute.groovy

The class PersonRoute where is the implementation of the service inside the method configure contains the following lines that will be explained now.

To enable an swagger API from the rest DSL you have to set the apiContextPath, that represents the path to access to the swagger documentation generated by Camel DSL, this apiContextPath will go after the leading context Path that was specified for the REST service

.apiContextPath("$apiVersionPath/api-doc")

To provide an API title you have to set the api property "api.title"

.apiProperty("api.title","Person Api")

To provide a version of the documentation you have to set the api property "api.version"

.apiProperty("api.version","1.0.0")

As part of configuration of swagger you have to set up cors in true it means that documentation will be enabled by access from browser an not by rest services.

.apiProperty("cors","true")

You can see this values inside the page that Swagger UI explore

The value of the base URL is taken from composition of host:port/contextPath

You can specify an API description adding this.description()

If you want to add a description for the methods (GET, POST, DELETE, PUT ) that you have in the service, you need to specify .description()after the method declaration.

and it will display like this

you can see the detail of the method making click in the method

If you want to specify a parameter with a description and a mark it with required you have to add .param()

and get the id object by its name and define that this parameter type with RestParamType.path (it could be body, formData, query, header and path) to specify if that param is required you have to set required in true and you will see this parameter marked with * and the text of required .

To document a Response Model that is related with a Response code you have to use Swagger Annotations. If we want to document the object PersonDTO for example, we have to add @ApiModel and @ApiModelProperty and set the options inside each annotation as follows.

and Swagger will interpret it like thisSwagger Automatically add the response models to the API document at the end of the page

If you want more information about the options that Swagger provides you can go to

Swagger Documentation