2.5 KiB
Swagger API Info Example
In this repositoryI 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.
My medium post here: https://medium.com/p/ef2ba65ebb86
Getting Started
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 you can find in the class SpringFoxConfig.java
First we will see how the swagger-ui looks without ApiInfo:
[Image of swagger-ui without ApiInfo](SpringBootSwaggerFirefoxAndOpenApiTestings\SpringBoot-SwaggerExamples\SwaggerApiInfoExample\dev_resources)
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).