Automatically Documentation - Generate Swagger UI from your Serverless Config

do you want to learn how you can automatically generate your swagger documentation for your serverless apis in this video that is exactly what i'm going to be showing you how to do [Music] hi guys my name is sam with complete coding where our aim is to make you into the best serverless and aws developer that you can be in this video we'll be looking at how we can set up a npm package and a serverless plugin that will allow us to automatically generate swagger documentation for our serverless api full disclosure this is an npm package that i have built myself because i hate doing documentation it takes time out and if you do it manually it always ends up that the documentation and what you've actually built don't quite match up so with this serverless plugin it uses your original serverless config to generate your swagger ui config creating this plugin has taken me weeks and weeks so the best way you can say thanks is if you smash the like button on this video as it helps this be shared with more developers just like yourselves so let's jump into our code and see how we can get things set up so i've just opened up a serverless project that i've created a little while ago and this is based off the serverless template called aws nodejs typescript so this is going to be very familiar to any of you who have used the typescript template to start with let's have a look at our serverless.ts so in here we have our custom section full of variables that we use throughout our project we then have our provider and our list of plugins as well as that we then have our functions and i've defined those in a separate file and if we have a look at those currently we have two functions a get flights with a single http method as well as book flights which has a post method so to get our serverless auto swagger working first we need to install it we do that by running npm install dash dash dev serverless auto swagger and whilst that is starting i'm going to copy the serverless auto swagger i'm going to head over to our serverless.ts file and find our plugins list now if you're using any of these plugins so serverless webpack serverless offline or serverless dynamodb local then you need to make sure that you put the serverless auto swagger before those that's because the serverless auto swagger does a couple of small changes especially to the serverless offline package so it gets processed in order and if you want this to work just make sure that is right at the very start now that we've done that we can save this file we can see that the mpm installation has finished and now there is one little thing that we need to do because if you're using the serverless webpack plugin with typescript we need to go into the webpack config.js and inside the resolve.extensions we just need to add one little thing which is dot js now that is because at the moment the way that this works is it actually generates a javascript file and that's so that this project will be compatible with both if you use serverless yaml and this project does work with serverless yaml or if you've used serverless.ts as we have done in this case if you're not using webpack you can forget about this step and hopefully there'll be a new version of the serverless auto swagger where you don't require this change to your webpack config but for now we do and once that is installed all we need to do in our terminal is run serverless offline start and as i said before there is a little bit of processing that the auto swagger plugin does before the serverless offline gets triggered and that is to generate on our left hand side this folder called swagger and this contains the code required to actually host and basically serve our swagger ui endpoint now that has finished running we can see we have the two end points that we expect to see the get flights and the post two flights to update it but we also have a get swagger and i'm just going to copy that and it also has a swagger.json and that is going to be an endpoint to serve the json so if you have your own swagger ui hosted somewhere you can just access that url so if we head over to a browser and open up the three port 3000 dev swagger we get now access to our swagger ui which honestly is really cool this has been generated dynamically from the config inside our functions and if we click on here we can see that we have a get request and a post request where the post request requires a flight id string parameter but that's all the details there are now the really cool thing is when we want to update our api so if we go back into our code and just kill the offline mode for now and go into our functions we have our get flights and our book flights i'm going to just very quickly copy the get flights and paste it at the bottom and do a fake api and let's call this um fake get we're going to have that triggering the same lambda but obviously if you are creating a new and a new lambda endpoint you would point it at the new code it's still going to be a get and i'm going to change the path to be fake if we save this and rerun our serverless offline start what we'll see is the fact that we've changed this and added an extra path for our api so once this gets generated into our swagger json it will then be able to be served and we'll see our updated api so this is just starting up inside serverless offline and now that has completed if we refresh the page what will happen is we'll see that we have this new endpoint this just means that as long as you have updated your original serverless config the changes will be continued and will be available inside the swaget ui which means that your api documentation and what is available will never be out of sync so if we want to have more on our on our api documentation than just a 200 response say for example we want to add what kind of data is going to be returned inside our functions we can find our http event and add another parameter of responses this is an object where we put the status code we want to return and then in here that is an object describing the response so first we have a description this description could be successful api response and let's just make sure i've typed successful correctly as well as a description there can also be a body type so body type and this is going to be a string pointing at the a the response type so the typescript type that is returned as part of this so in our case if we look into source and types there is this flight.d.t.s and what i'm going to do is i'm going to return flight just like that now in this case with the serverless auto swagger the first place it looks for is api types dot ts dot ts so in this case it won't look in the flights file so there are two ways of dealing with this one is to change it from flights.d.t.s to api dash types and that will work absolutely fine the other way is if we add a little bit of extra config to our serverless custom section the way that we do that is in our custom section we add a new variable called auto swagger and in this object we can define a couple of things the one we want to define is the type files and this is an array of strings pointing at the typescript definition files that we want to use in our case that is going to be a single file of dot slash source slash types slash flights dot d dot t s and if you have multiple different typescript definition files that all exports different variables that you want to use inside your swagger then you can just add multiple files in here if we save this and rerun our auto swagger so just to remind we we've set the type files and in our responses well we've added responses to our get flights with a body type of flight we can now rerun serverless offline start so now that that has finished compiling we can go back into our browser and refresh this swagger url and what will happen is we now have some models so this flight model contains all of the information about a flight as well as if we look on our get endpoint it says that a 200 response has a description of sex successful api response and then has an example of the model data this just means that now you never have to define the models for your swagger ui you can just pull them dynamically from the typescript definition files that you've already created so this works for a get where you create define the response code so here you have a response code with a description and then the typescript type of the response but what about a post request so if we look at book flights we can do something similar on here we can define the body type call this post flight body and now what we need to do is copy this head into our flights.d.t and then here export com sorry export interface post flight body and in here we can post whatever we need to in our type so in this example let's say we have a passengers which is going to be an array of passenger and then there is going to be a flight time and that is going to be a string so if we save this flight.d.t.s and make sure that functions.ts is also saved it will now create a new swagger ui when we restart serverless offline but it will say that the body that is required on this post request is going to have the type of post flight body again this takes a little second to create our documentation so over in our over in our browser we can just refresh the page so now that we've loaded this up we can see there is a post flight body defining the parameters that needs to be passed into the post and if we actually open up the post itself we can see that that is defined here and we can switch between the model and the example values for this request so with this i've now shown you everything you need to set up auto swagger in either a serverless.ts or just a normal serverless project and add things such as post body definitions as well as responses for any requests that return a response of course you can add more responses than just one i would expect there to be multiple different responses for each of the api endpoints that you create at least one for success and one for failure so as well as being able to run this locally and see your swagger locally if you were to run sls deploy it will actually deploy not only your apis that you have created but also the swagger endpoints so that you can make the swagger config that you've defined and your documentation publicly accessible if we head over to our browser and i'm going to paste in the link to a deployed version of the api that i created a little while ago we can see that this contains the get flights and the book flights and now every time i do another serverless deploy it will then update this whole documentation meaning that the deployed version of your system and the documentation for it are always in line in this video we've looked at how we can automatically generate our own swagger ui from our own serverless config using the auto serverless auto swagger plugin if you like this and you think you might use it in your own projects then make sure to give this video a like as creating this plugin took weeks of time and it's a great way of saying thank you to the developers and if you haven't done already make sure to subscribe down here and turn on the bell notification as we release serverless content regularly to help you become the best serverless developer that you can be so thank you and i'll see you in that next video

Channel: Complete Coding

Views: 980

Keywords: AWS, serverless, Serverless Framework, NodeJS

Id: vkTIM9MQ5Wc

Length: 18min 2sec (1082 seconds)

Published: Tue Nov 09 2021