Full transcript
0:00you know I think it's safe to say that
0:02most of the Java and spring boot
0:04developers that I know aren't big on
0:06writing documentation we kind of embrace
0:09that agile philosophy of working
0:12software over comprehensive
0:14documentation but when it comes to
0:17restful apis you need to document them
0:20because other people outside of your
0:23organization are going to be consuming
0:25them they need to know what the names of
0:27the endpoints are they need to know the
0:29par ERS to pass into various endpoints
0:32and methods and of course they need to
0:34know the the schema and the structure of
0:37the Json or XML data that's going to be
0:40sent to the server or pulled back from a
0:43restful API call and that is where
0:46Swagger comes in that's where open API
0:49comes in and that's what I want to show
0:52you right now specifically how to
0:54document your spring boot restful API
0:58with with swag
1:00and the annotations that that come with
1:03version 3 of the open API hi I'm Cameron
1:07McKenzie I'm the editorinchief over at
1:09the serers side.com and I have to be one
1:11of the world's biggest spring boot
1:13Advocates and at the same time I'm
1:15really a big fan of swagger and I want
1:19to show you how you can use some of
1:20those Swagger annotations in your spring
1:23boot restful apis to easily and quickly
1:27create documentation and that is what
1:29what we're going to do next if you want
1:32to use Swagger to document your restful
1:34spring boot apis there's a little bit of
1:36configuration that you have to do but
1:38it's not much I cover it all in another
1:40tutorial that I'll link to in the
1:42description but the basics are this
1:46first you need a spring boot application
1:48secondly you need a restful API to
1:51document I've actually got the code here
1:52that I wrote in a a spring boot rest API
1:55tutorial that I have on YouTube and you
1:58have to add some configuration to your
2:01Maven or grade old project I'm using a
2:03maven project here and you can see that
2:06I've added the dependency for spring doc
2:08open API starter web MVC UI that's the
2:12one you need if using spring boot
2:13there's a different one for spring web
2:16flux there's a different one for
2:17different projects so make sure you get
2:19the web
2:20mvcu if you're decorating a rest
2:23controller by the way if you're using
2:25Gradle just head over to Maven Central
2:28and uh you can get the cord Coates for
2:30Gradle over there in fact if you want to
2:32copy and paste the maven coordinates
2:34they right there as well so make sure
2:38you've got that all set up make sure
2:40you've made that configuration change to
2:42your Gradle or Maven project I'd even
2:45say maybe restart the project just to
2:48make sure that that everything gets
2:50updated and once you've done that head
2:54over to localhost 880 swagger-ui
2:58index .html and the basic documentation
3:03for your API will come up on the the
3:07Swagger page it's actually very very
3:10impressive you can see there's the the
3:12get operation there's put delete post
3:16patch get again those are all the
3:19different apis you can actually see this
3:20one takes a a path parameter I think uh
3:24the patch takes a query parameter so
3:27it's interesting it's actually giving
3:28you a bit of detail here but you know we
3:32really want to add more detail and more
3:34of an explanation of how to use this API
3:37and what the open API annotations allow
3:40you to do is decorate your code in a
3:43meaningful way and have it show up here
3:45let me give you a a nice little example
3:47I'm going to go back to my code and I'm
3:49going to go take a look at the post
3:52operation so the post operation in my
3:56application will actually update
4:02the number of winds by one so it's a non
4:06idempotent update of the Winds by a
4:08single unit um by one so if someone goes
4:12to SLC score wins they call this through
4:16a post
4:17invocation the number of wins in my
4:20score object the score keeps track of
4:22the wins losses and ties in uh in my
4:26application the number of wins will
4:28increase by one now I do have do you see
4:30the Red X there okay if you see a red X
4:33there you need your eyes check because
4:35it's a white X in uh red circle but
4:38nevertheless I do have to do a little
4:40Source organize import because The
4:44annotation for operation that I've got
4:46there is from a different package so
4:48I'll save that um and now uh I've got
4:52Dev tools installed for spring boot so
4:54it's going to do a restart I'll go back
4:56to Swagger I'm going to take a look at
4:57that post mapping do a refresh
5:01crash and boom we now see on that post
5:04mapping it says non aident update
5:07idempotent update of the Winds by a
5:10single unit by one so we've now
5:12decorated that method and provided some
5:15detail for it and similarly I've got a a
5:19patch operation where you can specify
5:22exactly the number of wins so the post
5:25increases by one like a game is played
5:27and somebody wants to increase the
5:28number of wins by one sometimes I just
5:29say want to say make the winds 100 um so
5:32that's a patch mapping and now there's a
5:34request parameter there that takes the
5:37new value for the number of wins I'm
5:39going to add this parameter annotation
5:41that says uh here's a new value for the
5:44number of wins do a control shift o save
5:48my changes that little red X goes away
5:51oh white X in a red circle goes away and
5:54so new value for the number of wins I'm
5:57going to come over here to my rest API
6:00click refresh and be like hey it's not
6:02there I don't see it well of course you
6:04got to open up patch but there it tells
6:06me right there hey uh what's the new
6:08value well that's the new value for the
6:10number of wins so pretty cool pretty
6:15interesting there's even a a little bit
6:17more updated uh not updated but
6:21extensive annotation it's called API
6:23response and I'm going to throw that on
6:25the patch mapping here right at the
6:27beginning
6:30and this one says that well if
6:32everything goes well we'll return a a
6:36200 code uh the description that will
6:38tell anybody asking about this is that
6:40it will update the wins WIS updated and
6:43the score is returned what's a score
6:47well it points to the score Clash right
6:49here saying that that's part of the uh
6:51the schema that this will use so the
6:54data that gets sent back to the client
6:56will follow a schema that maps to the
6:59score class I'm going to do a control
7:01shift o a contrl s watch the spring boot
7:06project restart and then come over here
7:09and do a
7:11refresh and now if I take a look at this
7:14patch operation come down here under the
7:17responses it says wins updated score
7:20returned it's returning application Json
7:23and of course the schema maps to the the
7:25score class wins lastes and ties so
7:28we're we're getting deeper into these
7:30annotations now by the way if you want
7:33you can actually annotate and decorate
7:37your schema classes so I'm going to come
7:39over here and take a look at my score
7:43class and I'm going to
7:46throw some annotations on wins losses
7:50and ties it's a the size annotation and
7:53note this is not a Swagger open API Java
7:58spring boot annotation it's actually
7:59from uh the bean validation
8:01specification Jakarta Dov validation
8:03constraints. size but I'm saying these
8:05values should be from0 to 100 so I click
8:10save I click refresh over here on
8:13Swagger and I'm going to drill down
8:15right to the bottom take a look at the
8:18score notice it tells me that the score
8:21is wins losses and ties and it also
8:23tells me that the max number is 100 and
8:28the minimum is zero so we're actually
8:31getting information from those
8:33annotations right into the schema
8:35creating that restful API documentation
8:38for your Java spring boot applications
8:41all pretty cool now by the way right off
8:44the bat we've got a little detail up at
8:46the top there it just says open API
8:48definition but if you've got your own
8:50API you want to update that so uh right
8:53at the top of my class and it's
8:55specifically your rest
8:58controller and there there's my score
9:00controller I'm going to add in this
9:02one's a little complicated I may have to
9:05scroll a little bit here control shift o
9:09to save all the changes but you can see
9:11that it it's got a reference to an info
9:14object the open API definition
9:17references an info object the info
9:19object references things like the title
9:21here's the score API in the definition
9:25um I put the word definition there so
9:27that when it appears we know that it was
9:28part of this anotation version one two
9:31description operations to help settle
9:33scores that's a bit of a joke but um so
9:35now we've got this kind of annotation
9:38that really describes the whole API in
9:42general and if I jump back to Swagger do
9:46a little
9:47refresh boom you'll notice that the
9:50title here has changed score API
9:52definition it says it's
9:531.2 and it says operations to help
9:57settle scores so all again things are
10:00are getting good things are getting
10:02interesting now by the way there's
10:04actually some some cool things that just
10:08with the spring boot API or or or
10:11standard Java apis so for example if you
10:14go to Spring boot application and you've
10:16got a a method that simply
10:20returns a pageable
10:23object and now with all of the Imports
10:27resolved we can now go and take a look
10:29look at how this turns out in the
10:31Swagger page now couple of things uh
10:33just make sure in order to get page
10:35resolved you need spring data installed
10:37and you'd probably need like the H2
10:39database uh uh linking to that at the
10:42the very least just so that spring data
10:44will start up uh when you restart the
10:46application but watch this that when I
10:49go to Swagger the schema will have
10:52changed significantly because of that
10:55that object that I added for paging so
10:58going to come down to schemas I'll do a
11:00refresh first come down to schemas and
11:03notice we've got the score but we've
11:06also got a variety of schema objects
11:09that help with sorting and pagination
11:12and looping through results that we
11:15might get from multiple queries against
11:17a large database so we've got the sword
11:19object with Direction null handling
11:22ascending the page object with offset
11:25sort page page size buffer page source
11:29and then of course we' got the the score
11:31class as well so all really cool
11:34additions to uh to your documentation
11:37that really we didn't have to do much
11:39right that would have just come
11:41naturally if we actually had a method
11:43that that did paging against our jdbc
11:47database um so super cool super
11:51interesting and do I even have that
11:54search method here I'll open up that
11:55search method and you can see that for
11:58the search method method it takes the
12:00the the page takes the size we can have
12:03sorting attributes in there so again
12:05it's kind of like all of this is getting
12:07integrated right into Swagger right into
12:10our documentation for us you can even
12:12see the the description of that
12:15schema getting very very interesting
12:19right now as we build our application
12:21okay so what's next well I think I got
12:23one last trick up my sleeve and it is uh
12:27working with uh controller advice and
12:31also some exception handlers so I do
12:34have a global exception Handler in this
12:36project although it's not doing anything
12:39so there it is right there I'm going to
12:42update its code and do a little organize
12:47Imports and essentially what I I've done
12:50is I've got a a rest controller uh
12:52advice stereotype on this class and as
12:55you can see it's an exception Handler
12:57it'll get TR tried whenever the HTTP
13:00message not readable exception is
13:02triggered you've got to list an
13:04exception to respond to there um and the
13:07response status that it will send back
13:08is I am a
13:11teapot okay it it is one of the statuses
13:14you can use any status you want um I
13:17mean be serious about it in production
13:19but continue created already reported
13:21any of the the standard HTTP response
13:25codes will be in here um not modified
13:29IED payment required service unavailable
13:33right so you put them all in there I
13:34just did I have a teapot cuz it kind of
13:36struck me as ausing um but now we've
13:39actually specified what what happens
13:41when the HTTP message not readable
13:45exception happen so let's save that and
13:48we'll head down into our Swagger
13:52UI do a little refresh over here looks
13:55like we need to restart the application
13:58oh I got a little error there that was
14:00my
14:01bad spring boot will restart come over
14:04just why I left a a little s in there
14:09and as we do this refreshing over here
14:11you'll notice that it actually says on
14:14this particular request response cycle a
14:17418 code I a teapot potentially could
14:21get return so this becomes listed as one
14:24of the the possible well that wouldn't
14:28be an error code status code that could
14:30be returned
14:31from one of these methods so you get a
14:34really good idea of all of the different
14:37things that potentially you can document
14:40here when you're working with swagger
14:43open API and spring boots so that was
14:46the global exception Handler
14:49here here we see my Java Bean that uh
14:54gets used as the the schema representing
14:57the Json that gets sent back and forth
14:58AC across the server here we see the pal
15:02file and here we actually see our
15:04controller and the controller is where
15:06really the bulk of all these annotations
15:08went open API definition the API
15:12response the path P not the path
15:15parameter but the parameter annotation
15:18the operation annotation as well so you
15:21get a get a good idea of well in this
15:24case how easy it is to use these open
15:27API SW Swagger annotations to help you
15:31document your spring boot rest apis uh
15:34you get to see how nice this Swagger
15:37user interface is to actually see how
15:40things are progressing and what your
15:43apis look like and then actually
15:44interact with and call endpoints on your
15:47code to make sure everything comes back
15:48properly and test the different
15:50scenarios um and I just think overall it
15:53is a a pretty sweet little technology
15:57for helping you document those spring
15:59boot restful apis anyways there you go
16:02that is Swagger open API spring Boot and
16:06rest apis in Java and how to document
16:09them now if you enjoyed that tutorial I
16:11want you head over to the server
16:13side.com I'm the editor and chief over
16:14there we got lots of great tutorials on
16:16Spring boot Jakarta e git GitHub adile
16:21scrum you name it um I do have a couple
16:23books you can see hibernate Made Easy
16:25back there so I'm big on jpa also
16:27Pickering a Springfield and there's also
16:28o uh Darcy Clute at scrumptuous on
16:31Twitter her scrum Master certification
16:33guide if you're agile and working with
16:35scrum I know a lot of people are getting
16:37100% on the exam by following uh and
16:40reading that book so feel free to check
16:42it out um if you're interested in me my
16:45uh Twitter handle is Cameron mcz so feel
16:47free to follow and finally if you're
16:50watching this on Twitter well why don't
16:53you subscribe