Ep33 - Laravel API Documentation Generator with Scribe | Laravel API Server

[Music] hey there sm when building an api server having a good api documentation is always something important to do not only just for reference for your future self but also your fellow teammates especially the front-end developers but at the same time it is a pain in the ass to write api documentation as a lazy developer i don't really want to build an api documentation site from scratch that would be too much work for me so is there a better way to do this well the answer is hell yes otherwise this video wouldn't exist there's a wonderful package called scribe that will do much of the heavy lifting for us and now let's go to its github repository and learn how we can install the package let's go to its documentation i'll copy the installation command and paste it in our terminal once it is done we'll also publish the config file of this package and now let's take a look at a config file for a bit there are quite a few options in the config file that we can customize each one of them is commented and they should be quite straightforward now there's one particular key that we should be a bit more careful which is the type configuration there are two possible values static and laravel if we set it to static scribe will simply generate a static html page we use this option when we don't need to apply any extra middleware or routing logic to view the generated documentation if we set it to laravel we'll be able to apply middleware and other logic to the documentation site for example restrict access to the documentation site so that only authorized user can view the generated api documentation for now we'll just leave it as static the next thing that you want to be careful of is the match option under the routes configuration the match option allows us to define which api endpoints that we want to generate the documentation by default any routes that has a prefix of api will be included inside a generated documentation okay now let's give it a test run we'll go to our terminal and run php artisan scribe generate once that's done if we go to a public folder you'll notice that scribe has created a new folder called docs first and inside it contains the source code of the generated documentation let's visit the generated html page we'll run our server and visit the documentation site and we see a beautiful web page with a lot of goodies in it we can see a quick navigation menu the main documentation site and also sample code and sample response isn't that neat everything that you can see here are customizable at the moment our main documentation looks a bit empty let's learn how we can add some stuff to it currently all of our api routes falls under the same group called endpoints in the quick navigation menu it will be better if we can group our resources into their own separate group let's go back to our code and see how we can achieve that scribe can pick up special directive that we put inside php docs so if we want to group the routes inside our user controller what we can do is to insert php docs on our user controller class and use the add group directive followed by the group name and its description once we're done let's regenerate our api documentation and check out the changes and now back in the browser you can see that our users endpoint are now living under the user management group instead of endpoints alright let's move on let's see how we can add a little bit of description on our get user request here the first line in the dot block will be the title of the request documentation and the second line with a line break in between will be the description and now we know that in this endpoint we're trying to read an optional request query called page size which will specify inside a dot block so that will be included inside the api documentation we can do this by using the query param directive followed by the parameter name and the data type which in this case will be integer after the data type we will put in the description for the correct parameter and we're free to put in anything that we want since we're using laravel paginator laravel will also use a page query parameter behind the scene which will specify which page do we want to view let's also put that down okay now we will regenerate our api documentation and see how our current parameter documentation will look like let's go back to our browser hit refresh and there you go we've got a nice list of all the query parameters that we specified in a php dot block now you'll notice that by default each of the query parameter is optional if our endpoint has a mandatory query parameter we'll need to specify it inside our php docs just put in the required keyword right after the data type let's regenerate the documentation and now back inside our browser the page size query parameter no longer has the optional tag on it beautiful now let's move on i'll go ahead and remove the required tag on the page size query parameter because it is not a monetary field we can specify an example value to be used in a sample code by using the example keyword right after the description so for the page size query parameter i would like to give it an example value of 20. let's regenerate the documentation and go back to our browser and as you can see in a sample code scrap is using our provider example value for the page size query parameter we didn't specify any value for the page parameter so scribe will randomly assign a random value to it we didn't see any data in a response because we don't have enough data in our database to account for nine pages of data so we should really give an example value for the page query parameter by default scribe will interact with our database in order to generate a response to show in the api documentation this not only applies to the get request but also the post patch and delete request behind the scenes scribe will try to wrap all database operations within a transaction and roll back the transaction once it is done with the response so that there won't be any persistent changes in our database although this is safe for most of the time there's still a chance that something will go wrong and the changes are persisted in our database how do we solve this well there are two solutions one is to get scribed to use a different database when it is generating the api documentation to do that we can create a new.env file and call it env.docs and this.env file will point us to a different database that scribe will use and to get scrap to use this.env file we need to specify it at a time when we run the php addition command by supplying the double dash env flag followed by the postfix of our env file which in our case here will be docs now this method will work fine however we'll need to create a separate database instance just for scribe to interact with the second method which i think is a better way is to use another scribe directive to specify which response that we are returning in this endpoint we're returning back a resource collection and the directive is called api resource collection so when scribe sees this directive it will not interact with our database but instead it will attempt to generate a response by looking inside our resource class and use our model factory to generate the fields right after the directive we need to specify the namespace to our resource class and on a new line we also need to specify the model that we want scribd to load inside our resource class which in our case here will be our user model alright let's test it out we'll go back to our terminal and just to prove that this is working we will clear the database and regenerate the api documentation and now back inside our browser we can see that we still got a response inside the api documentation even though our database is now empty beautiful now let's move on to the show request the show request has a url parameter which is the id of the user that we want to get specifically by default scribe can automatically pick it up however if we want to customize the description we can use the directive url param to overwrite the default documentation let's regenerate the documentation oops i made a mistake the url parameter name should be id not user let's try that again and it works now currently the response is a mess let's fix this this time the endpoint is showing a specific user it's no longer a resource collection so we'll be using the api resource directive and similar as before we'll pass in the namespace for our user resource class and we also need to specify the resource model let's give it a go and the response is now showing correctly great let's move on to the store endpoint now the store endpoint is a post request that means we're going to deal with request body and to specify the request body we'll use a directive called body param in a doc block our user store request contains two fields name and email let's specify them inside our doc block the directive that we need is called body param and the structure of it is pretty much the same as query param so after the directive we put down the field name the data type the required keyword description and example the store endpoint will return the created user so we also need to specify the api resource directive which i'll simply copy and paste from the show endpoint let's try it out we'll regenerate our api documentation go back to the browser and the response is showing correctly and we'll do the same for the update endpoint and also the delete endpoint for the delete endpoint we are returning a custom json response here so we can no longer use the api resource directive instead we need to use the response directive where we can manually define the structure of the api response we can also specify the http response code right after the directive all right let's test our code regenerate our api documentation and back in the browser we can see our update endpoint and delete endpoint are showing with the correct response and that is pretty much it this is a quick overview on how to work with the scribe library and how it can help us to easily generate api documentation the library has a lot of other features that we can't cover all of them in one single video i highly recommend you to check out their documentation the link is in the description we still need to write a documentation for our comment and post results i'll leave that as an exercise for you again the solution will be in the project repository and also one more thing before we end the lesson scribe will also generate postman collection for our convenience if you want to see our endpoints in postman simply import the collection.json file that it generates inside the docs folder alright key takeaway for this lesson scrap is an amazing package that helps us to generate api documentation in a beautiful web page we use the add directive in php docs to provide details about our api endpoints that's it for now and i'll see you again in the next video if you enjoy the content of this video don't forget to hit the like subscribe and the bell icon for more content to come it will really help me out thanks for the support [Music] you

Channel: Acadea.io

Views: 10,524

Keywords: laravel, api, documentation, best practice, api docs

Id: a3nQrBEtufw

Length: 12min 35sec (755 seconds)

Published: Tue Dec 21 2021