Swagger API documentation tutorial for beginners - 1 - Intro to API documentation with Swagger

hello everyone my name is Dave partner in this tutorial I'll be taking you on a journey through documenting your API and I'll just show you what this looks like we're going to be using one of the best tools for documenting apis called Swagger it makes documenting your API very easy and neat and it also helps people to test out your API so the developers checking out your API can actually test it on the the documentation itself and be sure it's working knows exactly what to expect before implementing it so here is swaga to to visit this site you just visit pet store. swag. pet store. swag. is a sample API documentation all the information here is just dummy information but they put it up just to let you know how swaga works so this is the default interface and it was built with HTML and JavaScript so if you already know some HTML and JavaScript uh you can download this interface and um edit it which we'll be doing further down the tutorial and you can edit it to match your website's theme or color and U this is it you have swager pet store you basically exercise your right to code from a file and that file will be a yaml file a a file that has um yo I'll will show you shortly but y like this when you that's where you you write the code that will display this this web page now look at what it looks like you have a description of your API and um very important links that the user will read and then you also have uh your schemes which could be HTTP or https or both that is if your API your website um is HTTP or HTTP as you specify it in the file then you also have your endpoints these are your resources you have a pet resource then you have several endpoints inside pet so if I minimize this you'll see that there is a pet resource there's a store resource in the store resource there are four end points you have get post get delete that is these different end points for each one I can click on it and see further details so but before then let us look at some other endpoints we have user endpoint user source with a description and several endpoints and that is how powerful this is then at the bottom you have models I will show you uh the models but let us look at one endpoint first so we choose a random endpoint that creates a user let's just say the one that gets um an order ID find purchase order by ID so let's just get this one take this one and um if you look at your right hand you'll see that you can try it out but before we check out the try out button we'll see that it has the different parameters the description of the parameters that we're going to send one is the order ID so when we visiting this end point we are going to see this order ID now this Endo every end point there is uh going to be preceded by this so the developer knows that hey I have to add pto. swag. and it has to be HTTP so I'll add HTTP petore swag. iv2 and um I will now add SLT SL orderorder ID in the Endo I want to send so you're now describing that the order ID must be an integer and um there is more description here for the guy and you're specifying that this the content type that will be returned when they make a request will be XML and also they can choose to get Json you understand so you're the one that specifies this if your system only outputs Json like the one with the designed in this tutorial the tutorial here it only outputs Json then we have to specify only Json now if at this point you've not you don't know how to build apis first then you have to visit my Channel my channel is youtube.com/ cbmg and when it opens you click on playlists and you're looking for this one API tutorial for beginners step by step from scratch so when you find this you see that there are 13 videos at this point in time that teaches you how to build API using a very powerful tool called laravel Lumen after building it then you can actually move to documenting your API so I'm assuming that if you've got to this point and you're watching this video you've already written your API or I just out of curiosity you want to see what API documentation is so in that code you will specify this application. then um a successful operation you you specify the responses so 200 means a successful operation 400 means invalid ID supplied 44 other not found you can specify as many as you want or as few as you want but 200 is always there by default then you have your example value which comes from a model so if we click on the model we'll see the model of the other ID you you are the one that created this model for order at the bottom so people can go go to the bottom see your model which is order and the the types the data types that is expected you understand so they can also see directly from the end point if they click on this model they will see this this is a very detailed API documentation and you know the most powerful thing about this tool is that we can actually test it so let's say your developer wants to the the developer wants to test this um particular Endo what they can do is click on try it out and um it's going to take them to they're going to enter the order ID you understand your system only accepts order ID so they're going to enter the order ID so we we're just going to say um just get a random order and hope that it exist in the P database and this is a button to execute remember you can always use your CSS skills to change this page to suit the general color scheme of your website so when you hit on it it returns something so the execution has finished and we chose Jason then it is telling us what it sent it actually sent this call request and uh this the header and this is the response that we got so we got the order with the IDE of 35 the pet ID of 70 quantity 25 the order was created on was shipped on 2014 and the status is very available and it's not complete and here are the respon headers that we received and here at the code it was successful you understand so any anybody reading your API documentation and has this kind of resource in the documentation they really enjoy your API very very well now let me show you how this is how you can create this page just one simple way then we'll go further down into the tutorial to show um other ways so you can visit editor. swag. and when you open it you'll see that the screen will divide into two where you will have your Yo which is like your source code and your front end here so this is the source code of this so um let me open it somewhere else all right I've opened my Mozilla and I've open editor. swag. I just wanted you to see the default that opens up and the way this works is that whatever you're working on if you close the browser if you close the browser and open it any other time you will still see that has saved what you're working on and you can continue with it so this editor helps you to generate this page remember this page is familiar that's what we just saw in our pet store if I should open my other this is it they they're very similar so what the editor does is is just um gives you the ability to write the code while um watching it change here so in in so in the next tutorial I'll teach you how to write this code and have it edit here and then we can see how to do it offline because offline is usually the best but I want you to know that this is yaml that is the code that's called yaml as you can see it doesn't look like most programming languages but it's very easy to see and these lines here kind of um give you guy it looks like python or something so see in the next tutorial where we will actually start working on this all right so we can document your API and have your programmers or or whoever else is trying to consume your API to be able to use it easily thank you very much see you the subsequent tutorial don't forget to like And subscribe to my channel visit the channel youtube.com/ c/b then P to the right and hit on the Subscribe button more and more videos are coming up by the day all right see you next time

Channel: Braintemple Tutorial TV

Views: 723,098

Keywords: cakephp, laravel, framework, php, html, web, evelopment, rapid, swagger, api, documentation, endpoints

Id: 7MS1Z_1c5CU

Length: 10min 9sec (609 seconds)

Published: Mon Jun 19 2017