Spring Boot | Tutorial 10: Swagger Documentation

[Music] hello everyone welcome to spring boot tutorial series by JR Academy this is tutorial tank swagger documentation so till now in our journey we have seen many important topics and if you haven't watched them then I recommend you guys go back and watch my previous videos and many more important videos are coming on various technologies so please subscribe for more and let's get started with this tutorial so in this tutorial we will look into swagger documentation tool and to understand more consider world without standards so for example remove timezone from the world and you will see the whole world will be confused and everything will be affected from transportation to business so basically we need something common and compatible right so same way in software world we have amazing coding skill and so much knowledge about handling big data as and much more things but to create successful software ecosystem we need to communicate we need to share this data and API is very good way to share and communicate but with rapid development and various frameworks and technologies we were in need of some guidelines or some documentation to create APA some standards so every time we create some APA we need to share it with someone so that other developers can work on this so this someone could be someone from your team or it could be somewhere in the other part of the world so so we need good documentation because good documentation can lead us to less confusing and faster development and the wrong documentation can lead us to big mess and additionally developer cannot make all this document himself because ideally developers time should spend more on the coding side and logic side so someone needs to do this documentation and so Edgar can solve all our problems so so swagger is a documentation tool that automates documentation with predefined standard and it is open source and spring have built-in support for that in this tutorial we will look into this tool how to configure them and we will see different feature of the swagger so first thing is to add swagger in our project and to add spring to add swagger in our spring but provided it's a three step process first one is to add dependency so if you see here we have two dependencies and the one is for swagger and one is for UI support so basically you I support it's a came later but if if you had just first dependency then you will be able to use swagger but the data coming from swagger will be in JSON form so it's not a human readable form and it's whether you I will represent the data to you in a human readable form and second step is to enable swagger from over code so after after putting dependency in our code we need to enable it by our code and the next step is to restart our application so that is very simple so let's get to our Eclipse and add swagger in our project so this is our old project that we created for our previous tutorial this is our basic employment man system and in this project we're going to add a swagger so as I mentioned we have three-step process to add a sweater so first step is to add the dependency so let me go to my browser and here I am opening my own repository and here I can search for spring fox swagger and here if I see this one spring Fox wagon two point nine point two and let me copy this and paste it in my palm dot XML files so I'm opening palm load XML and here it the very last I can add with other dependencies so deleting the comment and saving the file and now second step is to enable this from the core enable swagger from the core so there are a couple of ways to do that so normally I can do this from our remain true class but in real world we normally create our another separate class for swagger configuration so what I'm going to do is I'm gonna create one another class here the width with the same level as same level with our main class and here I'm creating swagger confit class and here so to enable our swag that we have one annotation enables like that too for version two and I and this one is a configuration file so I'm putting at the red configuration also so I'm control as saving it and then restarting my application so once this is yeah this application is restarted and if I go to my postman and this is the API v2 API - Docs and if I hit enter then if you see here we have all the information about our application API so let me go down so this is the equator because we already have actuator in our code and if I go down we have this employee ID which is a post method and we have all the other description such as parameters responses and all but this format is not a human readable form this is adjacent so spring would have another dependency which is have which have UI support so you can create UI on your own on this adjacent if you want or you can use inbuilt UI so let's go with inbuilt UI and here I can go with that swagger to UI dependency and he solves that and this one is ping boat swagger UI and I'm copying this and notice copying this dependency and again I'm going to my post for Pond Road XML and Here I am pasting it so this is let me delete the comment and there is one shortcut to rearrange our code which is control shift and f it will rearrange over code to a proper position so I am closing this and I am restarting our application and I'm going to browser and let me open here to localhost swagger dot HTML so if you see here this is the documentation of our API and we have if I go here this is our employee controller that we created and this is our basic error controller and this one is MVC another other actuator related another controller this is happening because we haven't this we haven't tell anything to swagger from where to pick up proper EPI so it is scanning our entire code basically so we have added swagger and we have seen the UI of it but it is not configuring yet meaning we need to specify the configuration so we have discussed previously that if we don't provide configuration spring boot will take spring would will go with the default configuration and that is what is happening right now so we haven't decided configure anything so spring boot is working with before configuration and to configure we need to set up a docket object so docket object is a builder and the sole task of this object is to provide a primary interface for the swagger and it will provide the sensible defaults and convenience method to configure swagger so we need a docket object for Springwood configuration and to create that we can use our bean annotation and here I can create one function that will return docket and let me give this name swagger and here and this function will return everything so here let me type like return and here new and this will return rocket so we have this constructor for that and we have documentation type as underscore two this is the documentation and the second option we gonna select here is function to create the API select and here we need to provide a path so this path is basically we are telling swagger to which kind of path we need to take so in credit I can do something like this art selectors and I can I have this option so you can use end you can use regex also if you will use let's say and then you can say you can do something like this so it will take all the ApS which is start with EMP but that we will go with any for now because we don't have much aps and we don't need any of this extra feature so I am doing any it will take all that I'm gonna provide base package to scan for the API so it it won't scan entire project it will just can particular particular package so that's and here the here the separate package for controller we can use I can pass that package so it will only scan that controller package so let me do something like and now I can do build so this will this build function will build the rocket object with this whatever options we have specified okay and let me save this and restart the application it started so let me go here and refresh this page so now you see we have only EMP controller so all the rest of the packages here before it was actuate or another spring related epa's we don't need them right so it is showing how only EMP there is a more configuration you can do here such as you can provide API info here instead of after Bill you can put something like API info and I can pass a PA info function object so let me create one function and name API info and this function will return API info object so this is also I can use builder to build ap info object and I can provide something like I can do title and here I can provide title we can say MP test project so this is the title of the project and here I can provide another thing description and here I can provide this is demo for swagger and here I can provide contracts so in big industries normally they have his contract and stuff so they have their licensing and stuff they can provide so many things here so they have admin related information here so let's say somewhere if this application is not working or the documentation is not working then they can contact it mean this is the licen if they have copyrights on up or they have paid version of the API then they can use this you can provide license URL because you want your user to read those so you can do it license URL here and if you have versions if you have multiple versions about your application so I can say 1.0.0 and and the last I can build so if I pass this function here then what is gonna do is let me restart this application if let me refresh this and if you see here all the information is here so this is EMP test project and we have this is for demo and this is website email address and then user information license and stuff so swagger have many import on a notation for better configurations and let's see one by one so in class level we have one annotation it's called at EPI and and it marks our class as a swagger resource meaning we will put this this annotation at the controller class that means that all the this is the swagger resource means whether we'll take all the API is from that class second we have is a for API level a notation for the better configuration and the first one is a PA operation so this if this annotation will describe the operation of specific URL and the second one we have is a PA parameter so this is basically for the request parameters and another one is we have a PA response it will describe the response of the API and the fourth one is API responses so this is basically an area of a PA response so let's say if we have multiple responses then we need to merge them and make an error so this will this will provide that feature and that the next one is the entity or model level configuration so in here we have two API is a PA model and a PA model property so if you remember in our previous tutorial we have created employee object which was the task of the employee object was to hold data for like first name last name and addresses so objects so this tube annotation will help so let's go to in our Eclipse and add these annotations and see what it can do for us next thing we have is to discuss about the feature so let me go to the controller and here if I open this controller so we have couple of a couple of annotations that we can use so let's say I can throw out something like this API and which is weather related a notation you can see here and let me select this and here if I go and hit ctrl enter I have all the information they got that I can provide so this is the value you can describe you can put a description you can put a value if you have authorization related information you can put it here if you have consumes Android use related information you can so or let's say you have multiple controllers but you want to categorize based on some tags so you can use this kind of tag and you can go out here let's say we have this controller is in a hello category if I say this stop the application and start the application if I go here and if i refresh this you can see I have hello I have hello category and inside that I have controller here so this way you can categorize your API is based on some condition or some logic or you can go with other annotations and provide enough information so the user can work on this but normally we use a value or description description is a deprecated from one point five but support is still there but we shouldn't use that but we can use value instead of this description and you can put here information and next we have is function level API function level and notations and that is with this particular API so here I can say I can use this API operation and if you see here we have this API operation and inside that I can specify value so here also I if I do control and space it is showing me all the possible value possible attributes and let's say if I use this value and if I say here get all employee details and if I control as cell stopping the server and restarting the server and if I go here in my browser and refresh you can see it is showing here the description get all employed details here okay so this way you can provide the description about your API at the API level next one we have is API responses so let's say we have multiple responses so let's check one response first and then now we will go with API responses if you a response and here if I say let's say I this API is returning 200 or HTTP code and we have message with it saying that successfully something successful successfully get and I'm saving and restarting my application and I am going here and refreshing it if open this you see here so you can see those thing here in description and you can provide examples also if you want to tell them that this kind of response you will get so this is default example but you can provide here with example a notation and example property notations and next one we have is a peer responses so I can specify multiple responses like this multiple responses like this and inside that I can put something like this and inside that I can put a list of EPA responses so it is basically just an area of API response but just yeah so in one tag you can specify multiple responses like this so you can put up you can do like this and this is showing the error because we need to import it so control space is the shortcut for that and so this way you can specify multiple responses and another notation we have is if you have parameter so in here we are taking this request body with employee right so I I can specify here something like this API API parameter and here I can specify value I am saving it and then I can provide another attribute such as this property is mandatory or not so required is yes US require equal to true if I hit save stopping application and starting it again so here let me refresh this and if you go here this MP is showing star equal to because this is required we said and here we put description hello world which is showing it so if you want to explain to the user that what kind of response you need what kind of feels it needs the description it is mandatory or not you can specify here and another annotation we have is the annotations for our model so I mentioned that this employee normally in database we have this kind of entities we use so we need to tell users about the object and what these objects what this object represents or what are the fields inside it so you can use these annotations and so there are two annotations here one is API model and here I can provide a value or a description and if I hit ctrl s it is showing me so let me provide description and here I can pass something like employee object and ctrl s stopping the application and so if you go here we have this model tab and if I open this we have employee there and here you can see the description that I provide and if you want to provide the description here at the field level you can provide with another notation which is API model property and here you can specify something like this you can provide notes here saying that this represents unique ID something like this and if I save this stop the application and if I restart this I can express this and here if you see we have descriptions saying this employee ID represent a unique ID so that's all for now in this tutorial but I recommend you people to go and play with swagger because it will help you to learn more tricks about swagger and it is really very helpful in real-world applications at the time of development because let's say UI so let's say UI and bacon we have two different team one UI team's task is to develop the UI and the back-end team task is to download the backend but we need to communicate so every time a developer cannot go and explain them everything so if you set up this swagger then just give them a link and they will go through the link and they will understand themselves so it will reduce so much work so that's why this is important so go and play with it and if you like my tutorials please like and subscribe and share because many more important videos are coming and so see you in next one till then like subscribe and keep learning thank you very much

Channel: JR ACADEMY

Views: 2,578

Keywords: Spring Boot Swagger UI, Spring Boot Tutorials for Beginners, Spring boot swagger 2, Spring boot Swagger configuration, swagger, documentation, swagger documentation, swagger ui, swagger tutorial, api documentation, swagger editor, swagger documentation example, swagger documentation generator, swagger documentation with spring, swagger:an api documentation tool, spring boot restful api documentation with swagger 2, swagger integration, jayraj, gondaliya, jr academy

Id: 5el3bvTLJKY

Length: 23min 3sec (1383 seconds)

Published: Sun Nov 24 2019