Swagger API documentation for Golang project

we'll look at the golang swagger apa documentation uh before that we'll go through these items we'll look at the what is swagger and open api spec basically basics and then we look at the swagger editor and then we'll also look at the frameworks that support the swagger and then i have created a golang rest api server so for that i have added the swagger integration so we'll look at the api documentation for that project so now jump into the swagger api documentation the open open api uh api documentation it the swagger gives the rest api specifications so you can refer the swagger documentation while creating the rest apis so it talks about how the rest api should be and what are the various parameters that we can pass and how do we create the various parameters to the the uh available endpoints um so there are get post uh delete patch so basically the crud operations so for those how do we create the apis so the swagger api documentation talks about that so so there is a swagger editor so using this swagger editor we can create the the rest apis the before creating your project uh before before starting your uh the rest api server you can come to the swagger editor and then you can create the apis so this is the left side is the editor and right side is the uh the output of the left side code so this can be created in a yaml or the json file so once you type here the [Music] output will be shown here for example i can show this one so this is the description of the api so if i remove the catalog so it get deleted here you can see so what you can do is basically you can the this is the paths uh from this uh section you can start creating the apis there's a api slash catalog and then id of the api this is the get operation so this is the description and this these are the parameters it takes this is the description of the parameter it says some catalog id and in path and then the requires equal to true and the type is integer and yeah these are the different options you can check the documentation and you can give the parameters depending on the requirement so once you type at the left side it will create the corresponding uh result at the right side so you can see uh these are the two apis the get another is the get get by id and then the test api slash get string by id and then this is the input that we pass so you can check the description and the parameters and then the parameter name description and the id you can pass so another thing so you can see the responses here so another thing about the swagger the ui is that you can directly try try out the apis so that we will see in the demo so you can give the id uh the parameter for that api and then you can click execute so if you click execute this will get executed so with this i mean for testing the rest apis we were using the postman client so here without postman client we can execute all the apis here this is about the swagger editor so in once you have this file either the yaml or the json file so you can see these options like you can you can save the ml or you can convert to json right you can import the file so you can do those operations and here you have a generate server so you can look at these are the various uh various frameworks that the swagger supports so you can look for the go server so if you click here with this the rest apis so it will generate the server code basically the stubs will be generated you can start the server and fill up the uh fill up the code so similarly you can download for any of your framework let's say for the java java play framework so for these uh you can there there's the one for php and so there is first spring so you can download the uh the server so similarly there is a generate client as well okay um so this is about the swagger editor so these are the various frameworks that supports so if you look at the go because we have uh created the go project so you can look at the go so here uh we we have this go swagger so using the go swagger library or the package we are we are adding the api documentation in the go project a toolkit to support your api development with swagger so this is about the uh the swagger editor and the frameworks that supports now we will jump into the uh the golang project that i have created so i have created and uploaded the i have created and uploaded the project into the git lab so so it's a git app so you can look at the code here so this is the url for it github jpal saga demo and then the uh this is the path this is the repo and uh so if you look at the uh the demo so we have the main.go so main.go is where the execution starts so so this is the uh i already if you already have the uh the rest api server you can make changes to get this fagger uh documentation the another way is where you can have the the doc uh the rest api is created and then you can download the server so in this uh i have a i have created the uh code on the edit ide myself so so it started with the main and then this is the setup server so you can see it's listening at port 8091 and i i have added only the few apis for the account uh with this understanding you can you can extend this for other apis and the different options you can add so you can categorize you can group the apis so the all the account apis are grouped here and you can also have the versioning for the apis so so i have created the create update and the delete these are the methods of the implementation for these so this is the you need to add this one before this i'll show you the packages that have used uh so controller is the my uh my local package to implement the methods uh for the apis so this one i'll explain uh after uh uh generating the swagger in it uh so these are the this is the uh the gojin project the jin framework for the uh rest api or the web framework for the golang so the swagger files swagger slash files and then jinswaggers so these two packages are used to generate the swagger documentation in this project so this is the uh these are the different annotations that we need to add uh this is this is the uh description the title version description this the these are about the uh project specific information so this is the base path is the slash api slash v1 and the host is the localhost 8091 so these annotations you need to add and then you need to import these packages and then you need to update your the apis you can if you want you can group if you don't want grouping or if you don't want the versioning you can leave this as well after that you need to add this one to get the swagger ui so the r dot get slash swagger star any jinswagger wrap handler and then swagger files dot handler so once you have this you will get the swagger ui so i will show you the swagger ui now uh so this is the my uh web server so localhost colon guide 091 let me check my server is started my server is running here so so you can see the welcome to the sample program swagger that's the message printed from here so i will come to the sample demo go lang so let me i have updated the message let me restart the server so i am starting the server now so the server has started it's listening on the port 8091 let me bring up the let me access the server you can see welcome to the sample demo with golang and in this url path itself you can access the swagger so this is my the swagger api documentation for my project before that i will show you how the swagger api documentation got generated so if you look at the annotations that you added is the main project specific annotations at main before the main method and then for each api method we need to add the annotations so if you go to these methods or in the controller package so this is the controller package in that we have the account.go so we have three methods in it the create update and then the delete account so for these i have added the annotations this is the create account or the create resource godoc summary is a create a account description creates the resource or the account directory so resource is basically my account so accounts and then the the this is the parent specific so the param is the name uh name uh it's a path variable the string required is true and then the the name so this will get appeared on the uh the swagger ui i'll i'll show that and then these are the the written the success failure scenario what are the things that needs to be written so for simplicity i have returned the string object so the string success and in case of failures i just returning the string failure and this is the path of this method so it is in the slash account and then the create this is the post method so similarly i have added for the update and then i have added for the delete so these are the three methods and uh once these annotations are added what you need to do is you need to generate the uh this you need to run the swag in it so i am in the source code of the my golang project and so i need to run the swag in it so this is my swag command and i am calling the init so if you have the main.go you can you can say swag.init if you have the file which is in different location or the different name you can use iphone g and then you can give path to that main file where the main method is present so i am running swag in it so it has run this completed the swag in it it has generated the docs so if you look at we have the docs folder that got generated so let me uh remove and try again r minus rf docs so the docs file directory got removed you can see there is no dock directory again i am running the swag in it so it has generated the docs folder inside docs folder we have the swagger.json and the swagger.yaml so you can check we have the swagger.go file swagger.json and then the swagger.yaml so these the json and the yaml which contains the specification basically the our api related information so using which it will generate the swagger ui here so i'll show that swagger docs folder here this is the one you can check this fogger.json and the swagger.yaml uh both are similar one is in json format one is in the yaml format so you can look at the paths this is where the api [Music] api starts so slash account slash create and this is of post and then the description parameters and the responses whatever the annotations that we added so those are included here so you can check the delete you can check the update so these are generated from the camel so now once we have the once we have the docs got generated so we need to import we need to import the we need to import the docs folder in the main.com so this is the important step so i have imported controller slash docs here so this is my the main package let me show you the uh code dot modules so that my module controller so that's the reason i need to say controller slash docs so if you come here you need to import like this it's this is internally used by the swagger to generate the swagger documentation information and give it in the ui so you can check that the generated apis here so let me start the server again go run so my server has started now i am accessing it so i am able to get it so for example if if there is some problem with this uh docs import then you will get the web server but you don't get the api information let me show that so my server has started it seems it's already have this one but yeah the ui will generate but you don't get the aps information will it will say the loading error but in my case i have run previously so it might be showing again let me stop and start again just started yeah you will get like this uh fail to load the api definitions fetch error but if you look at the ui got loaded but the api information is not loaded so you need to make sure this is got imported so if you are getting that kind of error that means you need to concentrate on importing the package properly so maybe the previously it is not said that's the reason it got loaded the apis let me start again i have uncommented the import docs import and i am running these i'm starting the server again so my server has started so so the these are the apis that we added in the annotations and this is the information which is coming from the uh from the main method annotations so this is the main method so you can see uh this is a demo server you can see the description this is a demo server so we are getting that string from here so you can look at the the accounts uh the post method the create account method this is the description for the method the api create api description these are the parameters the parameter name and the it's required is true so it is showing required here this is the name you can give the name here and you can try out so these are the responses so i have added the basic responses but uh you can extend this to add your actual uh error that you want to throw so we you can also add models the db tables but i have not included that here uh so you can try out these apis here so i am giving a test and then i'm just clicking execute so this got executed let me yeah you can see creating account creating account called for this one the message is coming from here so this is the create account and this is coming from the this method so this is the one

Channel: Jayapal

Views: 1,051

Keywords:

Id: 7NxMDc30x_Y

Length: 20min 4sec (1204 seconds)

Published: Thu Sep 02 2021