Documenting your API with Swagger 2
Tags: tutorial, springboot, java, programming
Published: 2022-01-31 13:15:43

![Jedi archives](https://cdn-images-1.medium.com/max/2000/1*g9tMh-Nn0gocNGwgDvJxhA.png)

So after having [built our API](https://dev.to/erwanlt/building-a-simple-rest-api-with-springboot-53mc) and then [secured it](https://dev.to/erwanlt/securing-your-rest-api-with-springsecurity-57f7), we will now document it to allow others to use it more easily. To do that, we will implement [Swagger](https://swagger.io/).

## What you will need

In order to follow this tutorial, you will need a REST API, so you can :

* Follow the [tutorial to built your API](https://medium.com/javarevisited/building-a-simple-rest-api-with-springboot-3f2e4b123ebb)

* Clone the master branch of [this repository](https://github.com/ErwanLT/HumanCloningFacilities)

* Having your own API ready

## What il will look like

![UML representation](https://cdn-images-1.medium.com/max/5424/1*-4H-EHMutQSg21bb1g0O-w.png)

## I document, you document, we document

### The first dependency

So, if we want to use swagger for our API, we first need to add a maven dependency

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

### The java configuration

To enable Swagger, we need to configure it, so let's create a configuration class.
{% gist https://gist.github.com/ErwanLT/0bf1a720652eaed3b574ebe51f7e066f.js %}
As you can see, in the method apiInfo, I describe the general informations of my API :

* The title

* The description

* The version

* The termes of service (url)

* The Contact to join the API owner

* The licence

* The licence url

* The API vendor’s extension

All these informations will be displayed latter.

### The JSON generated

So if I start my application and go to the [http://localhost:8080/v2/api-docs](http://localhost:8080/v2/api-docs), i will see a JSON representation of my documentation

![swagger-json](https://cdn-images-1.medium.com/max/3040/1*r4emRSBTD8z_VhAaAxWVfw.png)

As you can see, i find all the informations that I have filled in my configuration class.
But let’s be honest, a json file is good, but an IHM will be better.
So let’s implement this IHM.

### The swagger-ui IHM

To enable the IHM, we don’t need to do so much work, just adding a maven dependency is enough

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

And then, if I restart my application and go to [http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html), I can see a beautiful (all relative) IHM that display my API information.

![swagger-ui](https://cdn-images-1.medium.com/max/2176/1*6K4tTvp5TZwM0DrwCJj-gg.png)

So now we have our swagger IHM, but there is no true documentation on it, we have our endpoint, and if we extend it we have some informations, but nothing very documented.
So let’s add our documentation.

### Documenting our controller

with the previous step completed, if I expend the POST endpoint i should see something like this

![](https://cdn-images-1.medium.com/max/5524/1*ehI0qfCMAsLhmcN7TC7o3w.png)

So let’s add some documentation on my [controller](https://javarevisited.blogspot.com/2017/08/difference-between-restcontroller-and-controller-annotations-spring-mvc-rest.html#ixzz6OYNB9oii).
{% gist https://gist.github.com/ErwanLT/0ecffe452d0f278952e2eaa3364a434d.js %}
With

* **@ApiOperation** : I can add a more detailed description of my endpoint (value), and specified what it consume and produce.

* **@ApiResponses** : I describe the returns codes of my API, here the 200 and the 500.

So if i restart my application (again) I should be able to see the change

![](https://cdn-images-1.medium.com/max/5524/1*joOGe0LzCYY_a6_cAxwCsw.png)

![](https://cdn-images-1.medium.com/max/5524/1*UKyScMqmRi5X9NoghiRFYQ.png)

That’s better.
We have see that in my API documentation, that my endpoints are documented, but I also have a section about my models (what my API produce or consume), and these models can also be documented.
So let’s go and add some documentation on it.

**Documenting our models**

So I have my Clone class as my model, in here i have few properties that are not documented and it represented in my swagger like this

![](https://cdn-images-1.medium.com/max/2416/1*N--NazNwxdIBKSpWxAYUrQ.png)

Except the type of my properties, I don’t have so much info on it.
To add it we will use the **@ApiModel** annotation on the class and the **@ApiModelProperty **annotation on properties that will allow us to add definitions such as description (value), name, data type, example values, and allowed values.

SO now my Clone class will be like this :
{% gist https://gist.github.com/ErwanLT/46488b2f44ccbcd454c4a7d5fc1905bc.js %}
and in my Swagger-ui, now the model will be like this :

![](https://cdn-images-1.medium.com/max/2000/1*J8Te-bmUlMFRvZ59sveHcg.png)

As you can see the mandatory field that i have described have a ***.**

## Testing our API with Swagger

So now that we have our swagger running and well documented, what can we do with it ?
We can test our endpoint !
Scrolling through the swagger-ui page, you should have noticed this button in each one of our endpoint.

![](https://cdn-images-1.medium.com/max/2000/1*dGt-aUiJCsP3yQWe6bK2PA.png)

If you click on it, it will slightly change your page so that you can write the body of the request, or edit some parameter.

![](https://cdn-images-1.medium.com/max/2000/1*B8xlnkzOxrHYyYmpAQEvLQ.png)

Then you can execute the query against your localhost and see the result below.

![](https://cdn-images-1.medium.com/max/2300/1*OcgVtYiEqBe7nfEcC2qkVA.png)

Thanks for your reading time, as previously, the code used in this tutorial is findable in [this Github repository](https://github.com/ErwanLT/HumanCloningFacilities), branch swagger.