How to add Swagger to Spring Boot - Brain Bytes

let me teach you everything you need to know about working with Swagger in a spring boat application there's gonna be a two part video the first part which is this one and then teach you what swagger is and why you would need to use it after that we're going to learn the step by step process for integrating swagger into a springboard application and can generate a pair documentation out of the bus let's get started [Music] you think you know swagger well you might be in for a bit of a surprise because Fagor is a little more than what most people think of it as well swagger is this vast set of open source tools that can help you with API development in general okay it has tons of tools to help you with developing API is working with API is making calls to them and finally documenting api's this third thing is what has given swagger its popularity it's an excellent tool for documenting api's it has various ways in which you can document it and the most popular way is using something called swagger UI when most people think of swagger they only think of swagger UI but swagger is more than that however in this video we're gonna be focusing on this popular part I'm gonna be focusing on the documentation part of swagger we will learn how to use swagger to document our spring boot api's let's get the basic question out of the way first okay why do we need a tool for documenting api's well the scenario is this let's say you are an API developer you have a spring boot application that has the API ice with you there's all the controllers and the API end finds and all that stuff now you ask another developer who's the consumer of this API to access this API that you've created so the guy who needs to use the API there's gonna come to you and ask you some questions they're gonna be like okay what are the endpoints that are available to him what are the response codes that those endpoints would provide what are the methods what is the payload structure that they would need to provide what's the response structure they're gonna get what are the error conditions that they might have to handle man does this guy have a lot of questions the quickest way to answer all these questions is to prepare a document and write down all the details of your API in the contract and all that stuff and hand it over to them because if there's one thing that all developers love it's writing documentation all the time right well there's also this additional problem of even if someone were to write the documentation what happens if the API gets updated then they're gonna have to update the documentation all the time and they have to make sure it's always in sync so this is gonna be a constant and consistent problem to solve this has typically been a problem with API development in general and the popular API technology that we had before rest was something called soap and soap had documentation standardized using something called visited it was an XML lots and lots and lots of XML however recipes don't have such strict requirements for documentation and less strict specification so in general that's a good thing but we still need to have something that can also generate API documentation and this is where swaggered documentation tools come into the picture this is how swaggered works swagger loves you to create auto-generated documentation based on metadata that you have in your code alright so you add swagger metadata to your code and you tell you tell us what the api's are what they should be used for what the parameters are and so on there's actually a lot of information that swagger can infer from your code and method signatures directly but you can add more metadata and add these things like EPA description or any notes that you want the consumers of the API to know and all that stuff once you've done that there is a process that takes all this metadata and takes the code itself and generates elegant documentation and various different forms from JSON to fully readable HTML directly ok developers just write the metadata and the tool builds the documentation the reason this is awesome as if the API changes for some reason right the developer just has to update the metadata for the changed API and then the swagger tooling takes care of updating the documentation so as long as you're generating the documentation with each build there's no problem with outdated documentation or manual efforts anymore you don't have to update the documentation yourself all right so now that we have the benefits of swagger understood let's look at how we add swagger do a spring boot application right so how do you get it to document your spring bootie api's well here are the steps the first step is to get the swagger to spring dependency there is a specific dependency that you need to get added to the class path and that's what's going to be doing all the work swagger by the way is a specification for documentation and there are different implementations for it you're gonna be getting the spring implementation of swagger because swagger can be used in various other languages various other platforms not necessarily spring so when you're using spats Fagor with spring you have the spring dependency of swagger there is a specific dependency called Spring Fox that we're going to be adding by the way all right so next step is to enable swagger in your spring boot application as you can imagine with springboard you just have to stick an annotation in there and then you have swagger enable we'll look at that and then that should be sufficient for generating some out-of-the-box documentation swagger is going to look at your API methods your controllers and all that stuff and kind of figure out some basic documentation but you can have it do more you can configure swagger to specifically say hey look at this package or look at this sets of api's and all that stuff so you're gonna be looking at that too and then the final step which is also optional is you can add more details as annotations to your api's the EPS structure is gonna inform swagger about what the API should be but then you can add notes for example you can say hey this API is for doing this and then don't use this API use this other thing instead so you can add these little notes and add more information to your API to your model objects and all that stuff as annotations to those API so we're gonna be looking at that one too alright so let's get started you're gonna start by creating a spring boot project once I've created it I'll open it in IntelliJ if you're not familiar with how to create a spring boot project from the scratch refer to this card that's showing up out here for step-by-step instructions alright so now I have this project open and spring board it's called spring boots wagger to application and all I've done here is if I open the palm direction or you see here I just have this web dependency that's it right it has no dependency no swagger stuff it's just a simple web application and now we gonna be adding some api's for it in order to document api's we need some e pairs in there in the first place so I'm gonna be adding like a contact API right so gonna address book API so what I'm going to do is and add this address book resource basically it has it'll have like three API endpoints one is for getting all the contacts bonus for getting contact given an ID and the other is for posting the context so that it gets added to the list all right so I'm gonna go here and here is my address book resource that have created just an empty class I have three methods here get contact sticks in an ID return the contact get all contacts which returns a list of contacts and then the third thing is the add contact which takes in a contact as an argument and it just returns it blindly of course but then it also adds it to the list on the server now I'm gonna be adding a bunch of annotations for this to make these API endpoints the first thing is the rest of controller of course and then annotations on top of each of these get mapping with the ID get mapping with Slash and post mapping with slash so basically what i'm doing here is when you get a when you do a get request at the root you're gonna get all the contacts when you do a get request with the root slash ID you're gonna get that specific ID the contact with that specific ID and then when you do a post to the root with contact information in the payload it is going to add it to the list all right I have mapped this to the root URL and that's intentional because I will be changing it later and I'll tell you why all right but remember this for now we're just updating off of the root URL now I need something to implement this contacts list I'm not gonna be doing database and all that stuff because it's not the scope of this particular video people will be using like a concurrent hash map and save all the contacts in memory all right so when I mean when I'm adding a contact I'm gonna put it to that concurrent hash map when I'm looking up a contact I'm gonna be looking up from that hash map and then getting all contacts is basically getting all the values all right so I'm going to be using the hash map implementation and I create this concurrent hash map in memory and then get of particular ideas contacts don't get again all contacts is just contact stored values put into an ArrayList and then putting a contact is basically contacts dot but of an ID and the contacts it's basically a map of a particular ID and the that information as you can notice here I'm assuming there is a contact class so I'm gonna be creating that contact model class as well so here is the contact class with the ID name and phone nothing too fancy here is basic spring MVC and basic spring rest I'm just using this because it's good it's a good API starting point to document with swagger all right so now I'm gonna access this API using postman I'll be using postman client for making these REST API calls if you're not familiar with postman is just like a REST API client for making calls to the API is if you're making get requests you can do this in any browser but if you're making post requests a good API client that's handy and I'm gonna be using postman so this is what it looks like right so we have a place where you can put in a URL I'm gonna put in localhost colon 8080 I'm gonna be doing a get request it's obviously empty now I'm gonna do a post request to this to put a contact and then I'm gonna put a couple of contacts so in the body I am gonna choose raw and then here is this raw payload of ID name and phone which is basically what the contact of module requires I'm gonna put the header as content type is application Jason because it's required to make these JSON calls and then of course with us in the body I'm gonna hit Send and it is going to save this contact for mr. foo and then I have a mr. bar as well ID bar mr. bar say you send one more so we have two contacts saved as you can see here is written in the payload but now if I were to get at the root this time it's going to return me these two contacts right that I've just saved and I could also look for then I remove this payload because we don't need this for making a get request right get four URL returns those two and then I can access a particular ID and I'm gonna get that particular contact all right we have three api's now on to the actual fun stuff how do we add swagger and have a generate documentation for these three API endpoints well let's look at those steps one is adding the swagger dependency like I said we're gonna be adding the swagger dependency for spring boot and the swagger dependency is spring fox swagger - all right so I'm gonna open this up in maven central so here's what maven central says spring fox swagger - the dependency version is 2.9 so I'm gonna be copying that dependency version and adding it to my palm Derik zimmel I put it just above the test dependency over here all right so spring fox market - two point nine point two is the version import my changes IntelliJ thank you very much and then once it's downloaded you have the spring fox swagger deeper in see added to your class path that's step one all right now let's move on to step two enabling swagger in your spring good application like I mentioned before it's as simple as just sticking an annotation in there so we're gonna be doing that I'm going to go to this main application which has the main method and here I'm going to stick this annotation called enable swagger - and that's it swagger - is enable and dependencies of course from the spring fox package which is what we just added right this was this was the dependency that we just added this is what we're gonna be importing from if you're doing this in a real-world application I would recommend not putting this in the root class I would probably create like a config class and put it there but it works anyway you have to behave this annotation somewhere right you have to have the enable swagger - annotation somewhere and then swagger does enable that we can restart the server and then after you've restarted the server access the same thing in postman you have the same API spot now this time you're gonna get an additional API in your web application thanks to swagger so what I'm gonna do is I'm going to access that API over here localhost 8080 I - Doc's all right so this is the new API endpoint documentation endpoint that swagger has added take a look at this JSON documentation it has a bunch of properties about what what this is it has the host base URL slash all right I'm gonna collapse the tag section here so here do you see the path section is what's really interesting you have the URL path we have a get and it has the summary as get all contacts it's basically inferring the stuff from your method names all right so it doesn't have somebody to tell the reader but it's inferring a bunch of stuff it has a bunch of responses that can provide that's kind of like spring and me see out of the box whatever it supports and then you have the post at the root URL and then again you have the add contact and then you have the parameter which is whatever whatever you want to put in the body here's the interesting thing it's gonna tell you what the scheme of your post body should be it's scheme eyes contact we want to show that and then just a little bit you have a slash error which is again the spring boot default you have a slash ID which is the third API that we have exposed which was get contact and then here is the definition section this is the schema of your different model objects we have one model object here or just contact these three fields so it's gonna tell you exactly what you need to send you know to make those calls bunch of error codes response codes and all that good stuff so yeah we have JSON documentation right there this is a great but swagger can do some more stuff it can do much more stuff actually can provide human readable HTML documentation kind of using the same principles so what we added as dependency was for generating JSON documentation you can have another dependency that generates HTML documentation it's not just documentation which is readable you can actually interact with it which is super cool and that's kind of what caused swagger to be super popular let me show you how that looks like so the dependency for adding HTML documentation in your Springwood application is spring fox swagger UI alright so again it's the same dependency two point nine point two so I am going to be adding that to my pom direction I go right there below swagger - I'm gonna have spring fox swagger UI import the changes okay now the this just with adding this dependency you not have an end point at the root URL which has the swagger HTML documentation but here is the problem I have a root URL API mapped to my address book application so it's gonna take over all requests coming to the root URL so what I need to do is take my API out of the root so what I'm gonna do here is go over to the rest controller I'm gonna add a request mapping with a path as slash API so that I'm listening to slash AP and I'm not completely taking over the root URL so now this allows requests to get in and have swagger UI handle at the root URL alright so I'm gonna be restarting my application this URL localhost:8080 swagger UI dot HTML all right so it's the dot HTML file at the root URL you see this is why I had to move the API out now I can access this root URL dot HTML and then here you see swagger UI in all its glory it's not very very very fancy of course but there are a couple of cool tricks it has up its sleeve so we're gonna start with looking at the title which is API documentation very generic title because we haven't even told it what our application name is right it has no idea we can do all that stuff but let's take a look at this guy here there are two api's that this thing has exposed one is the address book or resource and then the basic error controller so there are categories of api's all right so I'm going to expand this address book resource here you see there are three API endpoints which is exactly what we need so I can expand these and it provide more details and here is the cool thing you can actually try it out you can click on the try it out button you can actually make these API calls alright so here is the the post to the root URL in order to make an API endpoint I'm gonna do that first alright so I'm going to post it auto fills the JSON syntax for your model and then I'm just gonna add the same values over here because we restarted the server right now versus an in-memory database all that contact information we had at last time was gone so I'm gonna adding this execute make a post request and this it's actually made the post request return the response that you can read in HTML writes we don't need postman anymore you can access this directly in swagger and see here is the request URL that you send here is the response that you get and let me add one more bar mr. bar and execute and now here we get the same response party I'm gonna go to get now get all contacts try it out click on the execute button here then look at this we have the response right here so this is super cool in my opinion you're actually making these API calls in your documentation directly rights is not just a read-only thing I'm gonna add this try this out as well foo execute and here is the payload so this page which swagger UI generated but literally no information we that we provided to it right so we didn't give it any metadata nothing like that we just enable swagger in our spring good application added the right responses and then it was just there this basic error controller are the api's that come with spring MVC so it's got all the stuff model shows all the model objects that we have so here is the contact model object again you remember kind of tie it back to the resource schema value that we saw in JSON it's basically showing that in a nice readable format saying okay these are the mortal objects that you have we have contact and then you have a bunch of stuff from spring MVC that's coming out of the box right so you have the error endpoints from spring MVC you have a couple of models model and view and view these are also coming out of the box from spring MVC that's also documented over here okay so this was just bare-bones flagger I think it's really cool how much we got we're just adding a couple of dependencies and one annotation we just got this automated API documentation that's always updated so whoever is consuming your API can always point to that endpoint and get the latest state of Commendation and nobody has to write documentation manual however the HTML documentation page server generated as less than ideal for example there are spring MVC related n vines and resources that we'd like to remove and then the labeling the name and the description is very very generic but if you want to add more details and add more context well we'll fix that in the next video but I'll talk about how we can customize your API endpoints to provide more information to swagger and generally get better and much more readable API documentation so see you that [Music]

Channel: Java Brains

Views: 373,832

Keywords: java brains, java, brains, koushik, kaushik, brainbytes, explained, spring, spring boot, spring boot starter, swagger, springfox, swagger2, api documentation, openapi

Id: gduKpLW_vdY

Length: 21min 9sec (1269 seconds)

Published: Wed Jul 31 2019