Getting started with Laravel and Swagger Documentation

A short tutorial on how to get Swagger running with Laravel. Documentation is the backbone of an application. It allows developers after you to understand how the application works without having to read through the entire implementation. Swagger is a framework that allows real-time authorization and endpoint testing for developers and testers alike. Setup Let’s start with a barebones application so we’re all on the same page. literally Composer First, we’ll need to download composer to make our Laravel application and download any dependencies https://getcomposer.org/download/ Laravel Using composer, we can create our new Laravel application composer create-project --prefer-dist laravel/laravel blog Local Development Server In this tutorial I’ll assume you have a basic understanding of editing your hosts file, so we’ll serve our application straight on localhost for time’s sake. cd blog && php artisan serve to stop the server. CTRL+C Swagger Swagger-php has been the most reliable and straightforward package to use on projects to generate documentation inside of Laravel. Installation composer require zircote/swagger-php Files & Scripts Swagger requires some information about our application such as it’s hostname, in this case it’s localhost. It’s important to keep files not directly tied to our application outside of the project root, so lets run some commands Create development folder and swagger scripts. mkdir development && cd developmenttouch swagger.sh && chmod +x swagger.shtouch swagger-constants.phptouch swagger-v1.php Inside our file, lets add a script to generate our documentation file swagger.sh Add the following inside your file swagger-constants.php Finally, add this inside your file swagger-v1.php Script Execution We can finally run: ./swagger.sh # Output Swagger-PHP 2.0.13------------------ -----------------------0 operations documented----------------------- It works! Unfortunately, we still have some more setup until we can start testing our application’s endpoints. Endpoint Documentation & Validation For this tutorial, we’ll create a custom controller called UserController ( ). app/Http/Controllers/Auth/UserController.php First, let’s create an endpoint where we can access this function. Routing In ( routes.php app/Http/routes.php ) add: Route::get('/create', 'UserController@create'); Controller For the UserController, we’ll use the following code: We can verify this endpoint works by testing it in our browser: cd .. && php artisan serve http://localhost:8000/create?firstname=medium&lastname=reader # medium reader Swagger UI So far we have our swagger documentation script working with it’s respective output. Now we need to add the user interface that will allow us to interact and test our endpoints. The script generates a subfolder inside the public folder with a file called which contains information for the UI about the endpoints and required data to test against. swagger.sh swagger.json /app/public|__ /swagger Installation In our script you may have noticed we specified which folder we wanted our swagger to output in. swagger.sh User Interface To add an interface go to and download the entire folder. Place it inside the swagger folder. https://github.com/swagger-api/swagger-ui _swagger-ui — Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful…_github.com swagger-api/swagger-ui Script customization Now that we have the user interface files set, we need to edit the file paths for swagger to work correctly. Our needs to be updated for our localhost server, you can copy and paste directly from here: index.html Swagger Annotations Annotations are the format of writing swagger documentation so they can be generated into and thus being testable. swagger.json Typically, annotations should be placed in your controllers that directly handle endpoints and validation ( ). app/Http/Controllers Let’s start by learning what the most important annotation blocks do. refers to what kind of HTTP method we’ll use, in this case, we’re fetching data ( ). SWG\Get() GET , the route of our endpoint “/create” path we have two parameters needed for our route — and SWG\Parameter() firstname lastname , the parameter will be passed through a query string query which kind of response and code will we return if the data is correct or incorrect. SWG\Response() Put the following Swagger annotations above your function and run one final time. create() ./swagger.sh /*** @SWG\Get (* path="/create",* description="Return a user's first and last name",* @SWG\Parameter (* name="firstname",* in="query",* type="string",* description="Your first name",* required=true,* ),* @SWG\Parameter (* name="lastname",* in="query",* type="string",* description="Your last name",* required=true,* ),* @SWG\Response (* response=200,* description="OK",* ),* @SWG\Response (* response=422,* description="Missing Data"* )* )*/ Tada! You should be able to access the final result . here End result of generating Swagger docs and Swagger UI Integration By clicking on our route endpoint, we can input the and and execute the GET request firstname lastname As with most tutorials, there is a lot to Swagger and documentation in general. I recommend you visit the on Github to get a better understanding on how everything works and the syntax involved in more complex requests. package Thanks for reading! View the original story at http://garrettvorce.com/laravel-and-swagger-documentation/