How to generate API documentation with apipie & rspec

hello i'm florine from wolfpack digital i'm a full stack developer and today we are going to take a look at api pi rails with um rspec for those of you who don't know api pi it's uh no it's an open source library used to generate api pi documentation it has its own view viewer and it also can be used to export the documentation as a swagger format for today we've prepared a simple rails application with a user model and another model called to do task task a user has multiple to do tasks it's a very simple model with title and descriptions description the user has doorkeeper and for that we created an api we have a basic doorkeeper authorization in the base controller and then a simple rails controller with some basic methods besides that we also installed rspec which is a well-known testing library in in ruby and we've created the rails helper and another request spec helper which we usually use in our tests to keep the code dry okay that's all the intro we have and now we can dig in let's start by adding api pyjam i have it here prepared but i recommend you to use rubygems to get the latest version api pi comes with a generator to set it up it creates an initializer and it also adds a route okay i'll go to the initializer and do some small changes in the configuration um we usually want to api to only include the controllers from the api folder because sometimes you may have controllers which are not part of the api so this is the the first change and then for this example we don't have any translations and we want to have multiple examples for the same test um another nice thing about api pi is is that you can have um authorization uh sim basic authorization on the documentation if you don't want it public that's it with the api pi initializer now we'll want to create a support file in the spec folder okay let's call it api by helper.rb and the reason we do that is because we want to be able to [Music] overwrite the the title in the documentation output so with this we can set the doc title property in our tests and it will display in the result now that we added this we want to require it in the rails helper file support api pi helper and also we want in the spec helper to filter only the requests the specs which have show in dock property and also only if we set this api pi record environment variable because we don't want to uh regenerate the examples every time we run the tests okay that's all we need to set up let's go and create the the folder where we put all the documentation let's create a folder called doc we want to require this this file in application rb this folder sorry um so we can add it here uh we simply added two autoload pads um okay yeah with api pi doesn't necessarily need this but we prefer to to put the documentation in separate modules to keep the controllers cleaner so all the api by dsl could also be written in uh in the controllers directly now i'm going to create a file for our to-do task controller called to do tasks controller doc dot rb and this is a simple module with some api pi dsl yeah we only have it for the index and create method for now we have a param group for the authorization with the header and the error code the param group it's reusable so we define it once and we can use it both for index and create and here for the create method we also have the parameters required to to create a new to-do task now that we have this in place we need to include it in the controller so we simply include the the module and that's it we can we can check the output yeah so as you can see we have a to do task resource with two endpoints get to do tasks and we have the header and the errors we can get and we for the post the create new tutu task we also have the parameters this is really nice but we don't have anything about the output uh that the the response we get from the server and this can be solved in two ways one is to write the examples the example output here and the other one is to use our spec to generate them and we want to use our spec because um it's uh we we anyways want to to write the tests and it's a nice way to keep them up to date to keep the documentation up to date because it's generated based on the api response so to do that that i will create the requests folder in the spec file folder api v1 and uh re to do tasks controller spec dot rb um this is where we'll put our test uh first i require the rails helper and now rspec describe api v1 to do task controller type request as a symbol do and if this block will want to create the the test first we need a user let's create it we don't have factory bot and faker but i would recommend you to use it on a production project it will make your life so much easier create email test underscore time dot now to integer just to make it unique at test.com it's not important right now password secure random dot hex okay we have a user um we'll also create three uh to do tasks for this user user uh to do tasks dot create title test description lorem ipsum and user user that's it that's what we need to run before running the test we'll describe the first endpoint describe get api lower case api v1 to do tasks do and now we'll have the first context when the user is logged in [Applause] when logged in do and before running the tests we need to stop the current user get api if you want to do tasks and we don't have any parameters we only have the authorized headers okay and we want we expect that the response returns our to do tasks it read users to do tasks show in doc because we want it to be included by our spec doc title get all to do tasks do and i'm only going to check for the oh what did i do i'm only going to check for the response status for now expect response to have http status okay and i'm just going to copy paste this context and create another one when the user doesn't provide any authorization token let's say it's uh not logged in context no authorization token we don't need to stop the current user and here we'll use the default headers okay and it returns unauthorized okay we'll also change this to let's say on authorized request and [Applause] okay so this is the the first uh end point and if we run the tests we hope they are going to pass no oh yeah it's a small typo headers okay and yeah now they work uh and if we run the server again and refresh wait a second and now we have the responses here uh and it's really nice it has the title the description this is the response code we got and then the the body and we have for all the scenarios um let's go ahead and create another endpoint for i'm going to copy paste and just change the the test uh i'm going to create the a new to do tasks right now so this is going to be a post request and we also need the params to do task title again i would recommend to use something like faker title description hello there okay and this needs to be transformed to a json okay it creates sorry new to do task doc title create new to do task okay let's save and hope that it works not this we want to record again the examples oh yeah for the create we expect the status code to be created so let's run them again it works let's start the server and hit refresh to do tasks yeah we also have now the examples for this one and we can see the we have here the parameters and then we have the response here this is really nice but as i mentioned before we can also use them in a swagger format so if we go to slash api pi dot json type equals swagger and we copied the the output or it can be integrated with a swagger editor but let's go to the swagger editor add the output here it will convert it into a ml and then we have everything here so uh right now the uh the specs are generated from localhost so of course running them here what won't work but if we automate this and run them on a staging server uh yeah they they will work or generate them with a different base url because it's configured in api pi initializer so uh yeah we we can set we can set the base url here right now it's localhost that's the default yeah so this is it this was the basic demo you can check um you can check the repository in the description and i hope you learned something new today thank you have a nice day

Channel: Wolfpack Digital

Views: 404

Keywords:

Id: 2qyOInhF4Co

Length: 17min 45sec (1065 seconds)

Published: Tue Apr 20 2021