Java Spring Boot REST API Documentation | What, Why and How of Swagger

code generation technique drag it out how it behaves Cloud vendor controller hello everyone very warm welcome to think constructive I am Isha in this session I will be talking about how to do API documentation more specifically for a string boot rest API projects all right I will be starting with what and why of API documentation followed by the tools and techniques to generate documentation automatically so be assured it will not be the manual documentation technique rather it will be the code generation technique and that complete explanation will be followed by the detailed demonstration in which we will be evolving our Cloud vendor API application all right so stay connected watch the session till the end so that you don't miss upon on any of the Core Concepts all right so let us start with the discussion now I'll first talk about what is Swagger what all areas it can be used and then we will be specifically focusing on the API documentation part all right so as you might be knowing Swagger has gained a lot and lot of popularity in the software industry because of its documentation capability so when we talk about documentation capability it's not like you are going to open any editor like notepad or wordpad or Microsoft Word anything like that and you'll start writing you know document over there no it's not like that Swagger makes it easy for developer to do the documentation with the help of code itself all right so that is where Swagger has gained a lot of popularity although Swagger can be used for variety of different ways it can be used to develop the API to create the interaction between apis and documenting apis other than that there are many more usage I'll now go through each and every usage of swagger it can be used for API design or development or testing or it can be used for API mocking API governance API monitoring and API documentation these are the majority of the areas where Swagger can be used but API documentation is one area where Swagger has really got lots and lots of popularity and the reason will be very clear once I'll walk you through the complete demonstration because then as a developer you'll be able to quickly relate and understand it has really taken out all the pain of doing the manual documentation away and automated the stuffs for developers all right so I have listed down here the majority of the capabilities of swagger let's quickly move towards API documentation and will focus and we'll see how Swagger helps us there all right so as we discussed Swagger takes a manual work out of the API documentation that means in code I should be adding you know some dependencies or some annotations and the things are done right it has a generating visualizing and maintaining API talks why do we say that when we say as a developer I am supposed to add certain kind of dependencies or annotations in the code itself and the document will be generated that means the manual task is gone and it will be Auto generated after generating that document we can visualize it via Swagger user interface as well as with the help of client tools such as Postman right when I talk about maintaining API docs that means as a developer we know development is ongoing process it's never like that the code is you know done and it will never ever be touched never like that right could continue getting evolved let's say in last release some apis has been written According to which the documentation was generated now in the next release there are furthermore you know additions in that API then ideally the document has to be updated accordingly okay so that pane also is taken away by Swagger from the developers and what happens whenever any API gets updated and Swagger is already integrated there so that will automatically generate the updated API documents so I hope this point is very very clear now let us quickly understand why API documentation is so important because whatever API is being made it will accept the request does some processing and generate the output which is response so what happens it works in request response structure these apis has to be consumed by some rest line it can be user interface it can be any third party application anything in order to make those client developers that can be your UI developers or can be third party application developers in order to make them understand what this API is expecting in request how the request structure should be what number of parameters it should have or what is you know URL it is having and how is it generating and giving the response back to the client those client developers must understand this request and response structure fully to consume those apis all right there is one way to write all those manual documentation keeps on you know changing that and getting into so many discussions all the time whenever there is even any simple single minute change happens isn't it in order to take away all these problems what Swagger has done they have automated the complete stuff okay so whenever there is any change in the API request response any kind of change documentation will be updated if you have integrated Swagger in your code and then client developers can directly refer that updated documentation and act accordingly all right so Swagger has made everyone's life very simple that is where it has gained vast popularity in industry for its API documentation other areas are also good but I am sticking to API documentation here in this session all right and here is a website swagger.io I'll quickly open the swagger.io website and we'll show you certain stars then we'll move towards demonstration all right so I'll just open swagger.io website okay so here is the Swagger website many things they give it for free and for Enterprise level stuff certain things are chargeable okay so those details you can just go down in this website sure and it is mentioned all right it is open source Swagger hub with these capabilities you get for free and in Swagger Hub Pro you get additional features all right so we will be using that our open source staffs API documentation will demonstrate you all right so this is uh the Swagger website and also one more point to notice Swagger is supported by smart Bear all right so the capabilities what I showed you if you come to why Swagger stuff you can see all these capabilities and if you would like to explore it further you can just click on anyone or whichever capability you would like to see you can just get inside that link and explore more stuffs all right so this is about Swagger website now I will quickly open IntelliJ IDEA editor and we'll start with the demonstration here is the IntelliJ IDEA editor I will be using IntelliJ IDEA for the coding purposes you can use any other Java editor of your choice all right so for this demonstration I will be further evolving our Cloud vendor API application the application which we have been building in our previous sessions so just in case if you missed watching those sessions I will highly recommend you to go ahead and watch those sessions I have tagged all those spring sessions link in the above card section as well as links are given in the description box below and those sessions are also getting flashed on your screen right now all right so feel free to watch all these sessions because right from session one we are taking one particular concept and evolving this application with the help of that concept for this session I'll give you a very quick walkthrough for cloud vendor API application so that you can relate the code what we are going to do now all right so inside source main Java what we have done we have built our comp thing constructive rest demo inside controller we have built Cloud vendor controller layer which is having all crud operations inside it all right then we have our model class which is our Cloud vendor class this class is having all the required properties which we want this Cloud vendor entity to have all right and this Cloud vendor is getting saved in the database with the help of cloud vendor inputable all right we have repository layer to interact with the databases we have uh then service layer okay to have all the business logic inside it all right and also we have done custom response handling as well as exception handling all these things we have covered in our previous sessions also in our previous sessions we have done unit testing full tutorial for all the grid operations so all those things are already available on the channel links as I told you can get from the card section above or from the description section below there is a playlist also created so you can you know reach to the targeted session by any means all those links I have already given all right so now let us start with the Swagger additions in this application okay so first thing we will see what dependency is needed in order to have Swagger in your application so in order to add dependency you should open perm.xml okay inform.xml you can see many other dependencies are there because we are building and evolving this application with every session for all other Concepts because this application is capable enough to save data in the database to query from the database to do exception handling to do custom response handling and also all the required unit test cases also for all product operations so there are many other things also involved here that is where palm.xml has many dependencies already so here for Swagger specific stuff I will tell you which dependency to add okay so what you need to do you need to just add dependency tag it will ask for the group ID and artifact ID so for group ID what I'll give I'll give io.spring Fox okay and in artifact ID you can notice it has already filled a spring box boot starter dependency just in case if you don't get it you can you know copy it and paste it there and version the latest version is 3.0.0 at the time of recording this session okay so this is just one form dependence you should be having okay I will also tell you from the website how can you get this dependency before that one more thing Swagger supports many other programming language so what we need to see we need to look for the Swagger spring specific dependency okay so that spring specific dependency is spring Fox Swagger may run dependency okay that's how you should search for it and then you should go to the maven link and you can notice spring Fox Swagger 2 3.0.0 is the latest one okay so we have added this only either way you can have you can just copy the dependency from here and add it to your palm.xml fine so you have added the spring Forks dependency specific for Swagger in your palm.xml you can now refresh the maven dependencies that is very important every time you add or remove any dependency or change any dependency details from your prom.xml you should do a maven refresh okay so it has got the required dependency after adding this dependency my spring boot application has become capable to generate the API documentation all right all the default things will happen and it will be able to generate document which we will be able to test via Postman as well as from Swagger UI I'll show you both the stuffs now then I will tell you which all customization what all is needed you can do all right I will now start the application and will show you how you can check the API documentation with the help of Postman as well as with the help of swagger UI okay and after that how you can do certain customizations all right what happened my application couldn't come up and I ran into some issues okay if you notice what issue it is talking about fail to start being documentation plugins bootstrapper nested exception all right after looking at this I can understand I have done just now some changes related to documentation and similar kind of error I am getting okay so I'll tell you the fix to sort out this error which is coming very frequently in the latest Swagger versions all right what you need to do you need to add MVC path match and matching strategies and path matcher okay because there are some matching stuffs which are still not sorted so in order to do that you need to add this kind of switch in your application.yaml or application.properties whichever file you are using and then you won't be getting this error all right so I'll just again start the application and we'll show you so this time you can notice my application is successfully up and running you can see this log started rest application cool yeah so my error is sorted now let's use the postman and see certain stuffs all right so here is a postman tool and let's say I would want to create one Cloud vendor application let's say we are going to create C5 cloudbender created successfully okay and in request body it is taking four parameters like this fine and let us now execute get by ID for cloud vendor C5 okay what have I got I've got a proper response wherein data is filled like this HTTP status and message fine let us now check the Swagger documentation using Postman so this is the URL for checking the Swagger documentation so I have already created the request what you can do you can just say a right click here add request okay select method as get and here you can give the URL okay like this so in the URL last things V3 slash API docs will be fixed here instead of localhost you can write the IP variable your rest application is up and running and the corresponding Port all right so I'll just say B3 slash API docs and we'll say send you can see down below I'll just come back to this you know in info kind of stuff so here inside Parts you can notice slash cloud vendor then get method right this is forget all correct that's what we have done responses you can see and then if you'll go down you can see put method likewise you'll be able to find out all the methods here their parameter details their responses details everything all right now I will show you how can you check the stuff with the help of swagger UI okay so for Swagger UI IP colon Port okay and then you should give Swagger Dash UI forward slash okay this part is fixed Swagger Dash UI okay and here you can see API documentation page is open API documentation URL is given here okay then server Stars okay and down below basic error controller Cloud vendor controller all these stuff so see get Cloud vendor okay put cloud vendor all these things five methods we have all fives are displayed and then in the schema you can see we have Cloud vendor schema so Cloud Bender all four properties are listed here fine but above it is written some generic terms API documentation then here also API documentation and then I am getting some extra basic error controller all these kind of stuffs here so so these things are Auto generated or you can say by default generated by Swagger so in my application if I don't want to have this basic error controller which is a default generation thing and also the default tag lines API documentation and by default terms of service or these kind of stuffs I want to customize them and to write my own these are doable and I'll now show you how can you do that all right so let us go back to our IntelliJ I will first terminate the application so my application is terminated fine now in order to customize I'll come back to rest demo application.java file wherein specifically my springboot application starter point is given okay and inside this I should be creating a docket beam okay so docket pin is responsible to Define that behavior if we don't give it it will take all the default stuffs which we have just now seen if I want to customize it I should be overriding all those stuffs here okay so I will first be annotating that as pin okay inside this I will say public pocket Trager configuration let's say I'm giving the name you can give any other name of your choice okay main idea is to have this docket pin fine this name can be anything inside this since it is returning docket so that means I should have a return statement which will be returning the instance this docket okay so I'll just say return new docket we should instantiate this docket pane with the help of documentation type Swagger 2 okay and further we should be defining a behavior which it should be building okay so ultimately this final return value will have a docket instance built with the customized data okay so I'll just say select it's a specific method we should understand what everything is happening here all right so inside paths I should give path selectors Dot and fine and here inside this I should be giving or defining the URLs which I would want to see finally in my Swagger documentation fine so in our case what documentation I would want to have cloud vendor okay slash star fine and then I should Define the apis now inside API I should Define request Handler selectors dot base package inside this I should give my package name wherein everything all my code exists so I'll give the parent package name here all right then finally I'll build the response try and save it fine now after building this complete response I should be passing the API information like what should be its headline what should be the license value what should be the email IDs all those kind of stuffs that can be done with the help of API info okay this API info is expecting see this API info object okay so let us build that object down here itself and we'll pass that okay so I'll now create a private method here which should return API info okay and I can give any method name here let's say I'm saying API custom data right this is what we are doing so similar kind of name I have people inside this API custom data I will be returning API info object why because this is what method should return and ultimately this API info is expecting API info object here correct so we are currently constructing that okay now inside this API info we will pass all the custom parameters which we want to have in our documentation all right so first thing you can see the Constructor of this API it is expecting title description version terms or service URL license license URL and vendor extensions all right so I'll just copy and paste it down below here so that we all can refer it okay and understand it in parallel fine I'll remove it later so first thing what is it expecting title okay so what should I give in the title let's say I will say cloud vendor API apply application all right then next parameter I would want to keep the description so here I will say cloud vendor documentation okay then I should give some version so let's say 1.0 okay all these things will be string terms of service URL so in terms of service URL let's say I'm writing cloud Bender service terms okay then next thing you should notice it is asking for contact and this contact is not a normal string rather it is a contact object okay so for that I should be constructing that that contact object so it is directly suggesting me okay it comes from a spring Fox itself so in that contact object I should be first giving the name URL and email all three will be string okay so first let's say I'm giving my name foreign is expected so I'll give the website URL here okay and then the email address that will also be the string okay fine so this is my contact object after that license is expected which is in string format so let's say I will write think constructive nice sense okay and then at last no last two are left so license URL it is asking okay so I'll just give my website as a license URL all right and then the last argument is when the extensions okay so I don't have any vendor extensions as of now so I will just say collections dot empty list I'll pass it as empty list fine so all the parameters we have built in here in order to customize our Swagger documentation all good and now I will pass this method here inside API info all right fine so what we are doing we are building a docket pane in order to do the customization for Swagger configuration and inside this all the required parameters path API all those stuffs we have passed and then finally for API info we have paid or rather we have created a method and we have passed that method directly here why now let us bring up the application and see how it behaves so you can see my application is up and running my start address demo application fine now let us go back to Swagger UI and see how it behaves now so here is the Swagger UI I have just refreshed it and you can see Cloud vendor API application instead of API documentation simply the version as 1.0 you can see terms of service and you can see website URL here social website I'll just open and show you this is thing constructive official website you can get many more articles here okay so if you wish to refer other stuffs or some more articles you can always visit this website fine send an email to Isha Puri so we have given some email address let me just copy email address paste it probably here in intelligent cell fine see the same email address we had built in here all right so now coming back to this and then think constructive license some license things we have given here down below you can now see only Cloud vendor controller which we are targeting to build and no more you know extra packages base error packages or the default stuffs so the moment I'll click on this Cloud vendor controller I'll see my five methods here so let me show you one by one I'll just go to get Cloud vendor get all Cloud vendor details will be displayed here okay and I can directly test my rest API from here itself okay so the moment I'll say that I'll just say try out okay since get all Cloud vendor details doesn't expect any parameter and here it is showing me if everything goes fine what kind of response we get all right so I will say get all Cloud vendor details and let me just execute since currently there is no data existing for the cloud vendor I am getting a blank response or blank in the response body why likewise you can go down and create a post request from here then put get delete all request you can try out from here itself okay inside the model you can see Cloud Vendor model one model we have so the same is getting displayed with all four properties right so that's how you can use Swagger for documentation as well as testing your rest API application as well fine now there is one more thing which I would like to demand straight although that is not you know kind of mandatory step that is optional step but it is always good to have you know good to do those things fine so I am back to IntelliJ IDEA editor I'll first terminate the application fine now I open my controller layer and will show you certain steps here currently what we have seen get all so it was written as get mapping or get all mapping those kind of basic basically basis on this method name the details we were able to see but if I want to make it more explanatory fine if I want that if someone opens that Swagger UI they should be able to explicitly understand in more detail what this get mapping or slash vendor ID is doing I can add an additional information with the help of at API operation annotation so here we can specify certain stuffs which will make it more clear what kind of you know value it accepts or it doesn't accept any value what kind of processing it does and what kind of responses it provides fine so let's say in value I will give what it expects tech specs cloud vendor ID right what it does inside nodes the processing stuffs we can write so I will just say Cloud vendor details okay and then let me just shift it yeah and then what kind of response it generates response is equal to what what response is it giving responsibility right so I'll just say response entity dot class good yeah so we'll just test it also so what we have done API operation what value it expects we have elaborated that okay foreign much more details here and then in the response what kind of response is it generating fine so by doing this a small change we have made this method notes or documentation much more clear all right now let me just demonstrate one more step here we'll coincide our Cloud Vendor model class okay if we want to Define what this class is exactly for and what each property means so that kind of detailed explanation also can be added here how can we do that for class at class level we will say API model annotation inside this we will add description for this class okay this table holds cloud vendor information all right it can be anything I'm just demonstrating certain stocks okay so that's how you can write a description for this entity okay so this is at the entity level at the properties level also you have certain annotations with which you can Define or detail out the stuff so I'll say API model property right model level we have given and now at the property level we can just write inside notes let's say for vendor ID we are writing this is a cloud vendor ID shall be unique okay so that's how you can write all the detailed information so the moment I have added these kind of information whenever my Swagger documentation gets generated it will have these kind of extra stuffs which will be more explanatory all right so let me just save and quickly bring up the application and we will see the changes now all right foreign the logs my application is up and running okay let us come back to the browser window and let me just refresh it just just close all this yeah so now what did we change we did change in the get by ID thing so you can see Cloud vendor ID is written here correct and inside this the detailing is written provide Cloud vendor details okay so here what it expects and here what this method is processing all that disruption comes here fine similarly if we go down inside model inside Cloud vendor you can see for this table the description is now written the stable holds Cloud vendor information and here for vendor ID this is a cloud vendor ID shall be unique so all those detailing also added here this will be very helpful for any consumer who is consuming your apis you know without doing too much of manual work all these things are generated all right although adding these kind of API model API model property API operation annotation and many more optional annotations are there to further detailing the documentation but these things are completely optional up to your project whatever things are expected but yeah it generally it is a good idea to give good documentation stuffs in your code good in order to maintain your code in longer run as well as in order to make consumers life easy all right let's summarize what all we have learned in this session we have discussed what in buy of API documentation what is it and why is it so important what tool we should be using so we have used Swagger so we have learned what in biof Swagger and Swagger is not limited to API documentation but this is one area which has really given great visibility to Swagger and that was followed by Swagger demonstration for our Cloud vendor API application so our Cloud vendor API application is further evolved to hold the rest API documentation and after adding Swagger to our Cloud vendor API application we have tested it using Postman and using swagger UI and further we have done certain customization also I hope these things are very very clear to everyone whatever doubts you have please ask your doubts in the comment section and whatever part of the code you found it really very useful tag that timeline in the description box below this will be helping everyone thank you everyone for watching this session I'm sure after watching this session and trying out all the examples you must be more confident for writing API documentation for your rest API springboot project if you haven't yet tried the complete example I will highly recommend you to try the example along with the session that will greatly help you there are more and more Java spring boot sessions available on my channel so feel free to explore them also ring the notification Bell so that you are always updated with the new and upcoming sessions on this channel because I'll continue bringing Java spring Boot and more related Technologies sessions here if you haven't yet shared the channel details with your friends and your colleagues please do so because that will help us to grow more stronger together as a community thank you once again see you in the next session bye for now [Music] thank you

Channel: Think Constructive

Views: 21,241

Keywords: spring boot rest api, swagger spring boot, think constructive, esha puri, how to add swagger to spring boot, java spring boot, spring, spring boot, spring boot restful api documentation with swagger 2, spring boot swagger, spring boot swagger 2, spring boot swagger 3, spring boot swagger configuration, spring boot swagger ui, spring boot swagger2, swagger, swagger 3 spring boot, swagger in spring boot, swagger tutorial, swagger ui, swagger ui spring boot, springfox, java, maven

Id: rsAigwGmTf8

Length: 38min 9sec (2289 seconds)

Published: Fri Sep 23 2022