Swagger & Java Restful API Documentation Guide

Swagger, the Usage Guides for our APIs

Hello everyone! Today we will learn how to use the documentation part, which is one of the most effective roles of developing, managing and maintaining a project, on our Rest API (Endpoint).

For example, you have created a method and a request will come here from the frontend, or you have opened an API service to the outside, whatever it is, I will explain Swagger, a tool where you document how that endpoint will be used, what you will probably get as a response, the necessary parameters and their types, and even whether it is mandatory to send.

In this article, you can directly access that part of the article directly from the links below, which we will cover from start to finish, which section will explain which features.

Content of the article :

• What is Swagger ?
• Adding Swagger dependency
• Inclusion in the project with Swagger Configuration
• Customization
• Documentation at Controller Level (Methods)
• Documentation at Endpoint Level (Methods)
• Documentation at Field Level (Methods)
• Hiding Endpoint in Swagger
• Hiding in Production Environment
• Using Swagger for its intended purpose

What is Swagger

I don’t need to repeat the same sentences since this section is clearly stated above. In its simplest definition, it is a documentation creation tool that contains directives and guidelines on how to use the endpoints we open to external departments (Mobile, Web, Etc.) or in other words how to use our Restful APIs.

In the images below you see the Swagger Interface. When we apply everything we have learned one by one, from adding dependencies to the end of the article, we will get exactly the following image.

Swagger UI

Endpoint Document

Adding Swagger dependency

In order to use the Swagger tool in our project, the first step should be to include the necessary library from the maven repository. For this, I provide package management in java and add the dependency you see below to my pom.xml file.

The dependency between lines 36 and 40 is the dependency I need. The biggest reason why I wrote this article is to show that with swagger 3, core code and ui dependencies are combined in one package. Long story short, let’s add this dependency to our library.

Inclusion in the project with Swagger Configuration

At this point, I need to introduce the Swagger tool to my java project, I need to specify in which settings it will work. After all, since this tool will handle endpoints and requests, I need to tell these paths to swagger.

First of all, I create my config class named SwaggerConfig.java under my config folder and configure it as follows.

I include it in the context with EnableSwagger2

I am defining the path of my Request objects with RequestHandlerSelectors

With PathSelectors I specify which endpoints to listen to. I used the /.* regex pattern because I wanted it to listen to all of them, if I only wanted to document under /home I would have used /home.

Customization

But if you notice, it is still not as in the image, right? For example, I want to include information such as the author, auditor, etc. of this documentation. Then I give an api info like this when building

Documentation at Controller Level (Methods)

From this point onwards, I will generally proceed through the code.

I give a value to my Controller with the Api Endpoint, by doing this I got the image you see below.

Additional Information : @Api annotation is not mandatory. If I didn’t use it, it would write login-controller-impl instead of Login Controller.

Documentation at Endpoint Level (Methods)

As seen in the image above, with the annotation named @ApiOperation, I have placed more understandable and descriptive directives in my swagger interface. now let’s see how these values are reflected in the interface.

notes : the text I specify in this section can be considered as a description, this is the part where we explain what this endpoint does to the Developer who will use the API.

value : this can be considered as a title compared to the description. The field where we specify which method to access in the service.

Additional Information : By entering @ApiOperation annotation, you can directly experience many features yourself. I mentioned 2 of them for example.

Documentation at Field Level (Methods)

Above is the part where I mark the mandatory ones from the Request Object that must be sent from the user to our backend server during the usage phase of this endpoint. In this example, I specify that it is mandatory to send this to the interface with @ApiParam. In the interface, it looks like this.

required : indicates that it is mandatory.

value : specifies the description part of the parameter.

example : used for the hint/placeholder part

Additional information: @CustomConstraint annotation, if you want to review it, you can also access that article HERE.

Additional Information: If you use @NotBlank and @NotNull annotation, swagger will automatically create required information. required = true is not enforced in this case

Hiding Endpoint in Swagger

Sometimes an endpoint can be critical, for example for payment, privacy or something that should not be implemented, but the endpoint should exist. At this point, you can hide this endpoint in swagger as you can see in the image.

hidden=true

It can be hidden with hidden = true, @ApiIgnore can also be used, but I prefer hidden to not define extra annotation.

Hiding in Production Environment

Since Swagger only makes sense in Development, you may want to hide it for security or other reasons.

We’ll see one of the best features that comes with Swagger 3, but first let’s see how it works in versions below 3.

As can be understood from the image, if the working profile is dev with @Profile annotation, only config will be created. But I do not find this control appropriate.

Current usage is as follows:

springfox.documentation.enabled: false

if you add this line to application-prod.yml, swagger will be disabled in the prod environment.

Using Swagger for its intended purpose

I’m sorry to say that most developers in the ecosystem use swagger thinking it’s an API testing tool. It makes sense to prefer it because it is easier compared to Postman. But it’s not!

Swagger is an API documentation tool, Postman is an API Testing tool.

Can you send a request with swagger? Of course you can, but imagine that you want a signature in the header part of the request… in this case you cannot test this api from swagger, or you want to examine the execution time, or you want to send a request directly to the PROD address, but we have hidden it in the prod? dozens of scenarios like this can be produced. Let’s adopt the Single Responsibility Principle by using each tool according to its nature.

Thank you for coming to the end of the article, I hope this article was useful for you, see you in the next articles and good work!