Spring boot 3 - OpenApi Documentation | Swagger UI

what's going on guys and welcome back to my YouTube channel in this video I'm gonna show you how to document your apis using open API and Swagger UI and it will be mainly for spring boot rest apis so also since the the release of the new version of spring boot which is the spring boot 3 so many changes have been done since that release so also I got a lot of comments from uh so many of you telling that you are no longer able to display the API documentation for your springboot 3 applications so I'm gonna work with step by step through the changes and how to implement that and especially how to implement rest API documentation for secured API so if your application has security implemented so it will be easy and I will show you how to do that if you're new to my channel go ahead hit the subscribe button and join us on YouTube also I would like to invite you to join me on social media you can also join our Discord server where a lot of people are helping each other and also you can join me on social media on LinkedIn Instagram so you can get all my updates that I'm publishing almost every day so with no further Ado let's get started before we dive into the code let's first have a look on the official website so if you go to springdoc.org you will you will have the open API 3 and Springwood official documentation so here we we see that this is a spring doc open API V 1.7.0 and we have a bunch of information here we see that that we have the introduction and then we have this Library supports open API 3 and also it supports springboot V12 and 3 and jsr 303 and specifically not for not not because this is really important when you have validation or you want to use validation in your application so you need to know about that also it supports the Swagger UI so we will have the UI to access the API documentation also it supports oauth2 and gruel VM native images so here we see that we have this important block right here and this one is really important because I got I received a lot of messages and a lot of comments saying that for people that are using spring boot version 3 they are not able to integrate or to include the the UI documentation or the Swagger UI documentation for their rest apis so here like if you go to the official documentation and this is what I'm always talking about first go to the documentation learn about it read and then you will get all the information you need so now if we click on this link right here so it says for spring boot version 3 support make sure you use spring doc open API V2 so this one is for prior versions so it doesn't support or it will not work with spring boot version 3 so if you have a prior version two point something point something you can use the V the open API V1 or the 170 at this time and then if you have a springboot 3 project you can use this one or you have to use this one okay so let's click on this link right here and then we have almost there almost the same let me close this ad so we have almost the same the introduction this Library supports and here we see that it supports spring boot version 3 Java 17 and Jakarta E9 which is really important because those are one uh one of the major changes in Spring boot version three so now let's go to the getting started and here for the integration between spring Boot and Swagger UI blah blah blah we need to include or to add this dependency to our project so now let's copy this and let's go to the code and paste this one now in our project let me open the pom.xml file and scroll to the to the bottom or wherever you want to put this dependency so just put it in here let me make it full screen and now I will paste this dependency then don't forget to click on this button to reload your Maven changes to download the new dependency and then let's start the application and see because when you have a springboard project all you need is to include this dependency right here and then you will automatically have your Swagger UI so let me start this and then let's go back to the browser and try to access the Swagger UI so here we see that we have already an exception I will just come back in a few moments to explain what is this so now let's go to the browser and in a new tab just type localhost 8080 or you like the application Port Swagger UI index.html and here the first thing that we can see we have a 403 why we have a 403 because we already have security implementation so without security this would work directly without any configuration without anything you need just one thing I want to highlight before we move on is this one so here we have a Jakarta validation exception and it says that unable to create a configuration because no other cards have been and so on and so forth and for this one you need to include the jsr 303 or to make it easier for you we can just add a new dependency which is the spring boot starter validation so the spring boot SATA validation is the validation dependency that we need now if I restart the application we will no longer get the exception and everything should be fine so now we have the exception because I didn't reload the project so this is really important let me reload the maven dependencies and now let me restart again so now as we can see we have no longer this exception and also we see that we have these tokens from the last video I published before so just go ahead and check it if you know if you if you want to learn about permissions and roles authorization in springboot okay so now let's go back to the browser and try to access this I refresh and again we have this 403 so 403 means that our Spring Security is not allowing us to access this endpoint or these resources so how to fix that let's go to the security configuration in here and then we see that we have these request matches and we are authorizing these URLs now we need to authorize other URLs that are required for Swagger UI in order to access the resources that it needs in order to display the information so here I have already the list so let me just bring this to a new line I will add a comma and then here are the requests that we need to authorize so this is um this is an extended list of URLs you can just use a V3 API docs and also this one and also you can enable the Swagger UI dot HTML and then it will be good you will be good to go and you will have your um your Swagger UI interface but I just wanted to include all this list in order if for example you are using a V2 documentation or if you have some issues so now you have all the list of the authorized URLs or the authorized resources needed by Swagger and open API so now let's restart our application and let's go back to the browser and see if we have again our UI so I will open the browser refresh in here and now we see that we have the Swagger UI it's just going to pop up in a few moments so let me zoom in and here we see that we have our management controller admin controller authentication and also we have the demo controller so here we see that we have everything or we have all the resources that we created in our backend and also now let's have a look or let's walk through this UI so here we see that we have this slash V3 slash API docs this means that this is the specification of the the back end or the rest API specification that we have and if we access this URL right here which is already the same you will see that you we will have or you will see all the application definition that we have for example we have this path for this get method we can access it using slash API V1 management which is the one that we specified in our controllers so for the people seeing this for this video for the first time I would really invite you to start watching this Spring Security playlist in my YouTube channel so like that you will understand what we are talking about right here especially when I talk about these endpoints alright so this representation right here is a Json representation of what we can see in here so this is a UI representation and this one is a Json representation and this Json representation is something really important because we can use it or it has multiple usages including reverse engineering and regenerating or regenerating everything whether on the back end or the front end just from this specification so I will if you're interested to I can show you how to use it in an angular application for example or in any front-end application in order to generate all the services and dependencies and models and so on so forth so yeah if if this is something interesting for you just drop a comment and I will I will make it for you all right now let's go back to this UI so here we see that we have a title this is the version and this is some some tags that we see right here and then we have the list of servers so by default it takes the default URL of the default server URL that you have which is localhost 8080 which is the port that we have right here and for example if you want to expose API documentation for multiple environments you can specify the list of servers that we have right here and I will show you later on how we can configure and how we can customize everything we see right here then we see here that it automatically scans our application and it takes and it's able to read all the resources and endpoints that we have so it will scan for the controllers or rest controllers that you have in our application and then it will display them one by one so for example for this management controller we see that we have four methods the ones that we created already and here we have API V1 management put get post and delete same for the admin and also for the authentication and for the demo controller if we scroll to the bottom we see that we have this schemas block so the schemas Block it's it automatically also scans all the objects that we are using including for example the register request and we see here that we have first name last name email password and role and this is the update that we made the last time and also if you click here it will give you the type okay and here for this role it automatically also detects that this is an enam and if I expand this one we see that I have three roles that they can use or I can assign as a user role so it's really important and it gives us really as much details as we need and the same for the authentication response and also the authentication request so I will I will let you play and check all these details now let's move on and let me show you how to configure and how to add properties and make customization on the API or the open API definition so let's go back to our IntelliJ and now I can close this one so in this case we will be using annotations to configure everything or to give more of a more of definition and properties to our API so we can just go to the security application like to the main application of the main Java class that we have and we can add the annotations here on this level but what I preferred honestly like I want to separate things so in this config package I will just create a new class and I will call it open API config so then let me make this one full screen and now I will just so it's going to be an empty class and I will just add some annotations in order to describe my API so the first annotation that we will use is called open API definition so this is the definition of our API and it has a bunch of properties so like we see Server security tag info and so on so forth so let's start with the info and here we can see in the documentation you can also download the source and see and here this info attribute is of type info and in this M4 annotation we see that we have a list of properties like title description terms of service contact license and so on so forth so this is how I learn things and this is how I know how to implement things so I'm just sharing everything with you so now in the info let's use this at info annotation and then we need to provide first of all let's say the contact and the contact is also of type contact so now the contact I can give it a name so it's alibu and we also have an email so this is my email if you need to contact me or to get in touch so it's contact at alibucoding.com so don't hesitate if you have anything also I would like to invite you to visit my website and check the courses that I have right there and also in the contact you can provide the URL and here this is the URL for my website so it's https slash slash audiblecoding.com so you can find a lot of valuable courses in here so I just I can give you the full URL so you can if you want you can have a look on it so now we can after contact we can add a description to our API so let's say open API documentation for Spring Security alright so after that we can also give it a title so I just need a comma and then title and for the title let's say open API spec or specification that's a specification and then I will just alibu just as small reference okay then after the title you can also give it a version if you have multiple versions or in case you are changing or adapting the version based on your project version so you can also and it's really important to have versioning with your API documentation after the version we can also if you have some kind of Licensing or if I'm not I don't know which license you can you can use or you will be using but you can also add a license and this might be part of the information that we can provide so here we say let's say license and here license name it can be under a MIT license or something else and then we can also provide the URL for the license and here let's say https slash sum url.com also after the license if you have some kind of terms uh terms of service you can also provide this information let's say terms of service and I will leave you just play and give some precise information about that so here we just specified the info now let's specify the servers so the servers it's a list of servers so we can provide as many servers as we need or as we want so here it we need because let me show you the servers is also a list of server So This Server is also an annotation containing URL description variables and extensions so let's go back so now we need server annotation and for This Server annotation we need the description so for example let's say local Dev environment or local environment so this for localhost and then we can also specify the URL which is in our case HTTP colon It's not https sorry colon localhost and then the port 8080. I can I will just copy paste this one and I will say for example I want to have a prod environment or a prod or something else and again I will use the same URL in here well you should not you should not use an external or invalid URLs but you need to use the correct one and the list of servers is just in case for example you want to use the same UI but with multiple URLs so for example if you have your application deployed on dev environment pre-prod and prod environment you can just specify the list of servers right here and then you will be using the same UI interface to access all of them okay so now let's restart the application and see the changes that we made so the application is up and running let me open back my browser and refresh again now we see that we have a lot more information as we provided so here it's open API specification alibu and this is the version We specified here this is the description the terms of services the alibu website if I click on it it will just redirect me to my website also you can send an email because it contains the email here we have the license its name and now when we scroll back to the servers we see that we have the two servers that we provided so the first one is the localhost and the second one is like is uh my my website URL and now we still we see that we have all the rest so for example I want to try um I want to try one request so I can click on in here and then I have this tried out so then I will need to click on execute but nothing is happening and we see already here that I have 403 because I did not provide the beer token or the JWT token so now let me show you how you can configure open API in order to accept beer tokens or even you can for I will show you how how you can change the authentication the authentication type for example if you are using basic auth or something else or even auth2 I will show you how or when to where to change it so let me go back to ntdj and now here after this open API definition I need to add a new annotation so before adding The annotation we see after the server if I add comma and here we see that we have security tags extensions and so on so forth so security I will go back to it later because we will need it so now to add security we need to add a security scheme so here we have our security scheme so first let's give it a name and for the name I will call it Bearer off okay because my authentication is of type beer token and then I need a description well it's not needed but it's just a description and here JWT auth description so because I want to show you where every information is going to to be shown and then we need to to choose the scheme so here we need a bearer authentication and this beer authentication I want to use the type so what is the type of my authentication or of my security scheme so we need to use the security scheme type and we have API key HTTP oauth2 or metals or also we can have default or we can even set it to basic so in our case it's an HTTP and then we can specify the bureau format so the format is JWT because we need to inject JWT token and where we want to inject this token we can use the in and then it's security scheme it's security scheme in and then we can choose if we want to inject it in the cookie default query header and so on and so forth so here if I can if I type it security scheme and we see that we have four values cookie default header and query so for our case we need to inject the token in the header so let me specify it as header so now let's restart the application so as you can see we can use annotation for everything and it's really easy and readable and I guess it's also more maintainable and we can also use a Java configuration for that or like we can create a configuration class for that and it will have the same result so now let's go back to the browser and let's refresh and I want you to focus to see the difference so I'm going to refresh the page right now and let's see what is the difference after adding this annotation so first let me close this one and as you can see here we have this authorize button popping up so now when I click on it we see here that this is the name because we called it beer auth if you change that name it will also show in here and the type is HTTP and it's a bureau token and here we have the description is JWT auth description here for example you can say connect to to to get your JWT token and then we need to inject it or to paste it in here so let me copy it and now this is the token for the admin for example I'm gonna copy this one and paste it in here and then I will click on authorize so now we have our token we can close it so let's try again one of the endpoints so we click on execute and again we are getting 403 so why we are get still getting all three even we configured Swagger or open API to include authorization and also when we see this curl um Command right here we see it doesn't include the beer token in the header and this because we did not specify the security requirements for our API so let's go back to uh our ntdj and here in order to fix that we have two ways of doing this so if you remember I told you here we have another attribute called security and this security is of type security requirement and we can specify many security requirements so we can whether do it on this level if we want to apply the same security requirement for all the end points otherwise if we have different secret security schemes or security security requirements for example just I'm just giving giving you an example in case you have a bureau token for some endpoints and basic authentication for other endpoints you can create multiple security scheme so here instead of security scheme you can just use security schemes here and then you can specify as many security schemes as you want all right so now even before updating this let me show you how we can use this security requirement on the controller level so I will open for example this admin controller and here just scroll to the top and here add security requirement so the security requirement we need the name and the name should be exactly this one the one that we specified so I paste it here let me restart the application and let me show you the difference so now if I refresh again so we see on the admin controller level now we we see this lock icon in here so let me just grab the token and then I will try to connect again or to access that one so here I will paste it in here authorize and then close I can close this one and let's try this one okay so if I click on execute we see even this curve command is different and we have the authorization as a header so we see this minus H authorization it's a beer and then we have the beer token that you specified also we see that we have a 200 success so this security requirement annotation that we added on the on the admin controller level it will take or it will use this security scheme that you specified in here and it knows that we want to inject this beer token in the header and it's appear a JWT format and it's of type security scheme type HTTP so now this is if you want to separate them and make it specific for each controller but let's make it Global for all the controllers because we know that our application is 100 secured by JWT token for all the endpoints so let's go back to our API definition annotation and then security and for the security I will just add this security scheme so I'll just make them all a new line so it's more readable and now if I restart the application and then refresh the swag UI you will see that all the endpoints they will have that lock icon and the beer token will be included for each request so I'm just restarting the application uh well not restarting but just refreshing the UI and now as you can see we have the log everywhere okay so if you try any uh any of these endpoints you will be able to uh to access them so here whether we can authorize authorize all the requests from here or even if you click on this icon you can also paste the token only for that one and then it will be also applied for the others so let's try it out execute and now we see that we are also injecting this build token in the header and we have this 200 the same if we use if we use a manager token and so on so forth it will be also working in the same way okay so now we saw how we can we can include security with open API let me show you now some um some enhancements or some uh let's beautify our Swagger UI so here we see that we have this management controller it's management Dash controller because the controller is called management controller in case you want to change the name I will show you how to do that also we see that we have just get and slash API V1 slash management and we don't know what this method or this action is doing exactly so also let me show you how we can improve this and how we can add some description and you can how to how we can add also a summary and so on and so forth so let's go back to our IntelliJ let me stop the application and then on the admin or let's go to the management controller because it's the first one popping up in the in the UI and here we see that we have management controller so if you want to change the name all you need to do is to include or to add this tag annotation and it has an attribute or property called name and let's call it management just management not management controller and then when we start the application and refresh the UI you will see that it's no longer called management controller but management all right after that let's beautify a little bit our endpoints so this one if you if you really need to well document your API and your different endpoints you can add these annotations otherwise if it's like clear and easy from the name to to understand what the endpoint is doing it's I I guess I guess it should be also fine otherwise you can you can add as many information as you want so here it's an operation and for this operation we have a bunch of properties too so here for example we have the description so let's say get endpoint for manage management or manager whatever and then oops and then we have uh we can also provide a list of tags or a summary so let's say this is a summary for management get endpoints all right also we you can specify the responses of this endpoint so this endpoint has a bench of API response and as you can see this API response is the one from i o Swagger UI or Swagger V3 and so on so forth so the API response has sorry it's an annotation in here and it has also a bunch of properties like uh description and here for example success and then we have the code of the response code and here let's say for example it's 200 when when it's successful you can also add so as many information as you need for example what are the headers what what are all the information that this endpoint or this API response includes and for example let's say we want to add another API response which is for example 403 and here unauthorized or for example token and valid or invalid token just an example just I want to show you how this is gonna look like also you can have or you can add a lot more of informations like the server security tags also you can give an ID because by default it will take the the method name as an ID you can also say if it's deprecated and also you can provide a lot of information like the method the responses What It Takes as a body and so on so forth so let's stick just to this one and let's restart and see what are the differences so now I will refresh the page and let's check together what are the differences so first we see that we have now it's called management and here this is a summary for management endpoint if I um open this one so it's get on get endpoint for manager so this is the description that we provided and here we see that we have 200 success and also in case this means that this endpoint or this specific get endpoint is doing this and that and it responds with Sexes and the code 200 and 403 this means that it's unauthorized or embedded token and so and so forth so now you know how to customize the controller name you can you know how to add operations and so on so forth so now for example we see right here that we have this demo controller and this demo controller that suppose that it's only for internal usages and we don't want to expose or like the outside world to see that we have a demo controller and also for example I want to hide this post and put mappings or operations for the admin controller so the the out sideboard for example only can use the admin controller to to perform get operations so let me show you how we can hide this without without the need to remove or to do anything in the code it's just one single property or one single annotation that we need to add so now if I go back to my browser and again I need to open my admin controller now let's say that I want to hide this post mapping uh okay I already answered so we need to use the hidden annotation so Swagger provides us our open API provides us with an annotation called hidden so let's say for example I want to expose only the get mapping so let me restart and show you the difference now if we go back so now I need you to focus on the UI so for the admin controller we have four endpoints if I refresh now we see that on the admin controller we only see this get method okay now let's hide the whole demo controller and the same way let's open demo controller and then we need to put the hidden annotation on the class level this time okay so let me restart and then let's see the changes so I refresh the page and now let's see what will happen so we have admin controller authentication and management so we no longer see that we have this demo controller so also I would really invite you to play a bit more with the annotations and with this open API configuration and let me know in the comments what you find out or if you find any anything interesting please share it with us so that was it for this video I hope you enjoyed it I hope it was helpful for you and now you will be able to implement and to add API documentation to your spring boot applications and as you can as you saw it's it was really easy and nothing complicated in that so that's it for this video and before you leave just don't forget to join me and hit the Subscribe button and also don't forget to hit the thumbs up button so I can continue on producing content like this for you guys thank you so much and see you next time

Channel: Bouali Ali

Views: 53,150

Keywords: spring, jpa, data jpa, mapping, onetoone, one to one, spring data, many to one, manytoone, class, generatedvalue, persistence, repository, service, jparepository, jpa repository, uml, class diagram, design, software, engineer, software engineer, java, jakarta, javax, spring boot, springboot, security, spring security, aliboucoding, spring boot 3.0, spring boot 3, spring 3, jwt, filter, authentication, authorization, bearer, jjwt, oauth2, github, social connect, social login

Id: 2o_3hjUPAfQ

Length: 35min 9sec (2109 seconds)

Published: Wed May 03 2023