Spring Boot | Using SWAGGER at maximum — ApiInfo

The main article that bundles all together and redirect to different features that you can implement in swagger UI is present here: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-9828ae9fb9d0

In this article I am going to show how to add ApiInfo object in your Docket so that you will have a more professional look on your Swagger UI.

ApiInfo is the object that allows you as a developer to add Contact information, descriptions of the API, terms of use, and other information that are less important from an implementation point of view but important from an organization point of view.

The majority of the time teams don’t focus at all on this small details because they bring no value to the API but as mentioned they bring value from the fact that it’s a small detail that can be part of a set of small details that together makes your application more enjoyable and most of all makes you proud of your work. We can consider it in IT “Nice to have…”

Adding ApiInfo couldn’t have been easier, so I present it by a simple example:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SpringFoxConfig {


    @Bean
    public Docket getDocketInstance() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfoExample01())
                .select()
                .apis(RequestHandlerSelectors.basePackage("ro.stefan.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfoExample01() {
        return new ApiInfoBuilder()
                .title("API Info - Title section")
                .description("API Info - Description section")
                .version("0.0.1")
                .contact(new Contact("Stefan", "https://medium.com/@stefan.paladuta17", "test@test.com"))
                .build();
    }

}

First we will see how the swagger-ui looks without ApiInfo:

Now we will see how the swagger-ui looks with ApiInfo:

So we can see that with the ApiInfo based on our example added a lot of new things:

Point 1: The title is now more personalized for your application, and this believe me it’s important when you manage a dozen of microservices each with their own swagger interface and you want to test them individually.

Point 2: We have a description section where we can add information that describes the point of this swagger interface or the business logic that this API’s expose.

Point 3: We expose an URL that can redirect the user to a main page of the developing team that manages this bundle of endpoints.

Point 4: We expose a way for someone to contact us. And this for me it’s the most important thing in an API world, you should make the effort to make the proper documentation for consumers and if that documentation is not enough then you should leave at least a way for them to contact you for a feedback.

Let’s get deeper in the details: the method .description() can be very powerful because we can add HTML code. Well actually it’s a bit fake the statement but in reality it’s called: CommonMark syntax (learn it and you can do amazing stuff).

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SpringFoxConfig {


  @Bean
  public Docket getDocketInstance() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfoExample02())
                .select()
                .apis(RequestHandlerSelectors.basePackage("ro.stefan.controller"))
                .paths(PathSelectors.any())
                .build();
  }

  private ApiInfo apiInfoExample02() {
        return new ApiInfoBuilder()
                .title("API Info - Title section")
                .description("API Info - <strong>Description</strong> section <br> testing something new <br> <table> <tr><td>1</td><td>2</td></tr> <tr><td>3</td><td>4</td></tr> </table>")
                .version("0.0.1")
                .contact(new Contact("Stefan", "https://medium.com/@stefan.paladuta17", "test@test.com"))
                .build();
    }

}

NOTE: the title and version properties are required, others are optional. The result:

Why should you dedicate precious minutes/hours on this small details ? if you don’t see the value, then just take as good practice as the smartbear company implies “[…] it is considered to be a good practice to include general information about your API into the specification: version number, license notes, contact data, links to documentation, and more.”

Conclusion: ApiInfo is an object that permits you as developer to populate your Swagger-UI with the following data:

• The title
• The description
• The version ( + the url)
• The Contact to join the API owner
• The licence ( + the url)
• The API vendor’s extension

thus making your API documentation look much professional and easy to read by any consumer and also enforce you or your team to keep an eye on small details (good practice).

If you want my code you can find it here: https://github.com/Kanames/SpringBoot-SwaggerExamples

If you liked the article please take a minute to offer me a clap 👏 or even buy me a coffee https://www.buymeacoffee.com/stefansplace (;