How to configure Swagger in Spring Boot - Brain Bytes

let's look at how we can customize Wagner in a spring good application to get more tailor-made and more specific information in your auto generated HTML documentation [Music] swagger is a pretty cool way to document your spring boris apx all you need to do is add the swagger dependencies and it automatically serves up an API documentation endpoint for you in HTML and JSON the HTML documentation allows you to interact with it and actually make API calls so that's super cool this is in fact what we did in the previous tutorial so if you haven't checked that out click on the card that's showing up here that's great but there were a couple of small problems with the generated documentation first problem there were some out-of-the-box spring MVC related stuff that swagger was documenting because swagger doesn't know it just sees api's and it documents them this includes both your application API is the cheer road and the spring boot slash MVC API is that just come along for the ride because of the fact that you're using the framework your models are included with the spring MVC models you'd like swagger to exclude all the frameworks up and include just the ones that you've written why you ask what's the harm in having those API is there well for starters it causes a lot of confusion adds a lot of noise to the documentation secondly if you add something in the API documentation someone who's reading the documentation is very likely to actually use them now if you later replace those framework api's or changed them somehow you break all their code that uses it and they're gonna blame you because you added those API sin the documentation of the first place so here is the first problem you need control over what classes and packages an API is that swagger considers for documenting now here is the second problem slightly less impactful but important anyway you notice this nice heading and description of this API documentation page API documentation who doesn't want a nice title like that well you don't you want to replace that stuff with your actual application name and description with your name your URL your Terms of Service your license and all that stuff right so this is the second problem we'll solve both of these problems by configuring swagger to give it more information about the project so that it knows what to put in those metadata sections so the way to customize swagger is by creating an instance of an object called a docket alright a docket is an object that's going to contain all the customizable properties that you intend for swagger to pick up when it's generating those documentation and the way you publish your intent is by making that as a spring beat right so in your project as long as you have a spring bean which is a type Duquette and it has all the property set swagger is going to be looking at that instance to figure out what it needs to do to figure out what's the behavior that it needs to achieve so all you have to do to customize swagger is to create that spring bean of type docket and then set the properties on it set all the things that you want swagger to do and it's just going to take it so what I'm going to do here is create a method which returns the docket and annotate it with the add bean annotation and that makes it a spring bean and in this method I need to create an instance of Duquette and return it and spring is gonna hold on to that right so I can start with a simple constructor to duck it new docket and then I pass in a documentation type dot slash and the score two so this is basically creating a new docket instance that is configured to use swagger two so this is a bare-bones docket instance you know you want to set your configuration on top of this instance now how do you set your configuration on target this docket instance is actually manipulated by following a builder pattern so here's the way it works when you get a docket instance you're going to call a select method on it all right the first step is to call the select a method on the ducking instance to get a Duquette builder object this is a builder object of a class called API selector builder now this builder has methods that let you customize how you want swagger to behave you can call methods on the subject to set everything you need and at the end when you're happy you called the build method on this object to get the prepared docket object alright so this is a typical builder pattern in action right you can either do a return the duck it has this or if you want to configure it you call the select method on it to get the Builder object put all the properties that you want and then when you're done call the doctor get the prepared arcade object so that's exactly what we're gonna be doing in the code now so I'm going to get I'm gonna do a dot select to get that builder object and then there are a couple of things that I'm going to configure here I'm going to configure the pots and then I'm going to select the API slash star pots so these are the URL paths where api's are exposed which means that the / error path is not gonna get included because I've said okay look at API is that start with slash API and then slash star I'm using the ant pattern here this is what the path selectors that ant is using there's another configuration that I can use which is package based configuration so here what I'm doing is I'm using the api's configuration and I'm specifying what are the packages that it needs to look at so here the base package is I order Java brains and I'm saying only look at I order Java brains for the base package don't look at anything else this is another way in which we are excluding all of the spring related configuration and saying don't look at all those just look at this base package so this also excludes the modules we looked at a bunch of mortals that were included saying hey look at just the space package means it's not going to look at all those other classes so we're doing two restrictions here one is restricting based on the be URL off the API second we're restricting based on the package name so with these two we are kind of excluding some of that spring MVC stuff and then I'm gonna do a dot del and this is what this method is going to return now now that I'm returning this Duquette instance spring is gonna hold on to this and this is what is gonna inform swagger about how it needs to behave now I'm gonna restart my application and this time when we open the API documentation we should ideally see just our stuff as you can see here the error in point is gone and then the other models are gone we just have contact information alright so with this we've solved the first problem of making sure the documentation is just documenting kpi that you want to expose ready with this method you can get control over what swagger is looking at let's mortar the second problem adding some application metadata we want to fix that first top section which is API documentation and some generic information you want to add application related information which is specific to your application so that's the next step we're gonna do adding application metadata adding this metadata is pretty much at the same place where we did the Duquette right so when you create a Duquette you can also add api information to it and this is how you do it when you do a build just actually before you return that build instance you can call the API info method on the docket object directly alright so you don't need a builder for this for specifying the paths and the API is you have to do a select set the configuration and then do a dot dot for setting the API info you don't need to do a select you can set the API info directly on the Duquette so what I'm gonna do is after I do a build before I return that instance I'm going to do a dot API info and then this is going to take in as an argument and API info instance alright so there's a bunch of stuff that you want to set in that API info instance I just need to call the constructor and said those properties but since there's a lot what I'm gonna do is create a new method for it and then pass that in over here I'm gonna go over here create a new method I've just copy pasted this because there's a lot of verbose code so here I have created a new API info object I'm calling the constructor and that's constructor is taking a bunch of arguments you can probably get a sense for what these arguments are looking at the values that have passed you notice this contact object that I'm passing over here and passing contact information for API info so this is different from the contact class that we have locally in our project so I created a contact class this is not that right so this is a swagger contact information class so I am using the package reference to get to that thing and not my class all right so basically what this is doing is contact of name URL and email so there's a lot of information over here you can look up the API info documentation page to kind of get more information on what what are the things you need to pass and what are the things you can pass over here but basically what you need to do is create this object instance with all the API information and then all you need to do is so I'm just gonna stick this over here call the method from the API info and then what you're returning with Duquette is with the API info so I'm gonna restart this and you should see the result chain and it does now swagger is using all of the API metadata that we have passed him all right now with this we have a little more customization for our swagger documentation but there is more you can do you notice all the api's that we have provided we have a bunch of information that swagger infers from your API X so for example the first API is get contacts it's looking up the name of the method and putting that in the documentation there which is great well what does it API do it gets contacts which is perfect but what if you want to add more information what if you want to have like a note to whoever is using it and say hey this is what this API does or this is what this API should not be used for right so some extra information that you want to document well for that you can add more details to the api's by using certain swagger annotations now this is entirely optional you don't have to do this but if you want to provide these kind of notes to the readers of the documentation this is how you do it and we start by adding an API operation annotation so for this get contact API I have added this annotation called at API operation so there are a bunch of things that this annotation takes so the first is the value which is the text about what this API does it's kind of like a one-line description of what this API does right now it's taking that description from the method name get contact but with this annotation in place it's gonna say this API is fine contacts by ID which is pretty informative there's also a notes value which basically adds a little more description and I also have a response value which is contact our class which is basically saying the response of this API is gonna be that particular model all right just one annotation you can put this on top of each of your AP eyes and it's gonna give that description to whoever is reading the documentation all right so let me restart this and I'll show you how this looks like now refresh the page and now you see the get by ID has some more information it's not just the method name anymore it is the description that you've added and it also has the notes that you added so whoever is looking at this API will know a little bit more about that API itself there are a bunch more annotations like this I'm going to breeze through a couple more for example you have an annotation that you can use for method arguments which are basically input parameters for your REST API so let's say there's a post request and we want to annotate more information about what the user needs to send in the post body and what if there is an argument to a get request so let's say there was a path param in this case let's look at the gate contact you have a path variable which is the ID what if you want to tell people what that ID should be well you can specify API param annotation alright so what this does is it provides that extra notes to the API parameter in this case the IDS right so this annotation over here gets that value out to the swagger documentation next let's look at module objects you've seen contact and we've seen how spag are kind of interests that this is a model object it had ID name and phone but what if you want to add more description what if you want to add more description to the contact class itself well there are a couple of annotations that you can use there is an API model an API model property API model something that you put on top of the class so that you can specify notes about the class itself and that API model property is something that you stick on top of each member variable of the class so that you can specify notes about that particular the variable alright so if I were to restart and load the page again and here you see the model has more descriptive notes so there's a lot of annotations that you can use I definitely encourage you to look up spring fox swagger annotations can have annotations for response types errors a whole lot more now as you can see there's a lot of annotations that we are adding over here right so every step of the way for the class level for the method level for the field level learning a whole bunch of annotations and the more specific you want it to be the more information you want to convey the more annotations you need to add so this is a common problem that a lot of people have criticized swagger for as long as you use it in moderation things are fine but the more and more detail you add the more and more annotations you're gonna add to your code and then you're gonna get into the annotation health problems the annotations have more line numbers than the actual code itself if you don't like this and you kind of reluctant to use swagger because of this reason well there's an alternative for you there's a project in the spring ecosystem called spring rest Docs which is gaining popularity off live and since this is a part of the spring ecosystem it kind of works well with spring boot as well spring restocks has a pretty interesting concept it solves the problem of having too many annotations in the main code by saying hey why don't we move all this information out of the main code and into test code click on this link to watch that next and learn about spring restarts I'll see you there [Music]

Channel: Java Brains

Views: 137,557

Keywords: java brains, java, brains, koushik, kaushik, brainbytes, explained, spring, spring boot, spring boot starter, swagger, springfox, swagger2, api documentation, openapi, docket, apioperation, apiparam, apiinfo, apimodel, apimodelproperty

Id: 8s9I1G4tXhA

Length: 15min 21sec (921 seconds)

Published: Fri Aug 02 2019