Now that we have done the RESTful web service, it's important to add API documentation to our service. Otherwise, when we share this to some customers who want to make use of our REST endpoints, now it is very difficult for them to read or understand our API's. And many of the occasions, we wouldn't be sharing the source code with them. So how do we do this? Now this is where you have a fantastic API called swagger. So if you go to swagger.io, you can learn about how API development is simplified with the documentation of swagger.

Now, I don't want to go too deep into how this works. But I want to show you how to add swagger to our application and get the API up and running. So the first thing we want to do is to get the swagger so if you go to spring initializer and look for swagger here, you may not see that now somehow Spring Boot does not have default dependencies included over Hear, so we may have to explicitly go to MV and repository comm and look for swagger to press enter. You can see it comes from IO dot spring Fox dot spring Fox swagger two, so I'm going to select that. And the current version happens to be 292. So I just have a copy this go back to our POM dot XML, add this as a dependency.

So I can go to the end of the dependency list here and paste it. Save this and now I have one dependency that is added. With this dependency we will be able to scan and get information about all the APS we have. If you want a graphical user interface that displays all the API's provide some testing options, then you have to add one more dependency which is from let's go to swagger UI and if To see that it's again from IO dot spring fork, spring fork swagger UI. The version also is the same thing 292. I copy that, once again, go back to my POM dot XML, add as the last dependency, save it, it's going to download the jar files for the same.

There are two more steps involved in enabling swagger. Number one, we go to application dot java. And we say that we want to enable swagger documentation. So I'm going to go here and then type at the rate enable swagger and it says enable swagger two, and we have to add a bean definition here. So now what is this bean definition? Now when we say enable swagger to it's going to look for an object that is going to scan your entire project for all the API's and then build the documentation.

Now this is called as a docket. And the way you do that is by typing public docket. So Docker is supposed to come from spring Fox documentations Spring dot web dot plugins. And then we can call any name we want. Let's call it as API. And we have to return some docket object.

So with the return new docket, and then we supply a, what version? So you can see that it says, What's the documentation type? That's argument. So we say your documentation type dot swagger one, or swagger two. So we want to say swagger two. Now, technically, we should be able to return this object and everything should be okay.

But this gives us configuration as well. Now we have to mark this as a bean. So that spring automatically instantiate this object. And then this Docker object can be used for reading the API documentation. Now to specify some configuration here we say here dot select, and then this is what to say, what appears to be selected which says select the API's like dot API's and Then say what are the AP is that we want to document and we say any request handlers or dates such as the get mapping, post mapping, etc. So we want that.

So we say Request Handler, selectors, dot any saying that any type of handlers we want. And then we also say any type of paths that we want to specify. And again, you can say path selector of any. Now, once again, we are seeing that we want to just document everything. But here is where instead of saying any I can add some filter saying that a provide documentation for only get handlers not for post, or I can say slash API slash secured should not be included, etc, etc. I can do that.

And then I can say, bill to finally build this. So the lot of documentation configuration you can do over here. Then let's let's see, what is the error here? So we see some kind of a console log. Let's see what is that It is your class not found docket. So this could be because when we actually added the Maven dependencies it was still building.

So we may have to stop this once. Let's clear the console and run the application once again and see if everything is okay. Alright, looks like everything is fine. It's being scanning, you can see that scanning for API listing references. tonker has been started application has been started in 10 seconds. So I'm going to go back to the browser and first look for something like localhost 7777 slash, and then I type your v2 slash API docs.

Now, this is where you will be able to see some JSON documentation, representing a lot of information. Let's copy this and open in postman let's paste it press enter, you can see that it's going to give me a JSON representing lots of API URLs. Now, this is not very useful for us. But this is going to be used by swagger UI. So how do I get into that? Very simple, you just have to say your swagger UI dot html.

But when I press enter, you can see we get Hello Spring Boot. And this is because we have mapped the slash to this particular Hello Spring Boot. Now what I can do is I can just change this to slash Hello. So that when slash Hello is lost. This is the answer that we're going to get. If you are accessing the root of your service, then swagger UI should give the response so now if I explicitly access slash Hello, we get this Hello Spring Boot.

But if I say your swagger UI dot html, and now you should see that we got an APA documentation over here. Now the APA document Addition includes application which has a slash Hello, as one API. There is a basic error controller. Now, we did not configure any error controllers. But if we do that we will get, but there is a slash error with all get head post, etc. So this is not configured by us.

But you can see customer rest controller. That's the name we gave in our application. So if it's expanded, you have slash API customers get all customers is a function of the handler for the same. There's a post for API customers, there's a get put and delete for this particular URL. If you select API customers, you can see that I'm able to supply some parameters. Also here, it says there's an underscore limit underscore page as query string parameters that are optional, because there's a default value of 10 and one here respectively.

These could be the possible responses if it is 200. There's going to be okay. Example values and so on and so forth. Now, what you can do is you can also test the same thing by Clicking on try it out. So let's do that. When I do that it says, These are the two values defaults Do you want to execute, let's execute and see.

And it comes back and say, Hey, this is how you do a C URL or curl. So like on a Macintosh or Linux, I can just copy this and paste and I should be able to get it on a terminal. But if you want to access from the browser, this is going to be and this is the response that we got, or we were supposed to get when we make a request. And of course, there's some options to download, and so on and so forth. So this is how you use swagger to create API documentation for all your micro services.