Chat with us, powered by LiveChat

This website uses cookies

Our website, platform and/or any sub domains use cookies to understand how you use our services, and to improve both your experience and our marketing relevance.

Setup Laravel 5.7 Application in Just 1-click on Different Cloud Providers Like GCE , AWS , DO , Linode , Vultr Deploy Now!

Why and How to use Swagger with Laravel based RESTful API

January 6, 2016

2 Min Read
Reading Time: 2 minutes

When writing an API, it’s always a good idea to give the API users an interactive visualization of your complete API. Things can get more awesome if the interactive tool can be used as a playground to test your API. Google’s OAuth 2.0 Playground is a good example of it.

Recently at Cloudways, we started to create an API for Cloudways Platform and we wanted to give our customers the most convenient tool to explore our API. For this purpose, we evaluated different frameworks and finally went for Swagger.

restful

Swagger is a language/framework agnostic ecosystem to produce and visualize RESTful APIs. These days, Laravel and Lumen are becoming the most widely used frameworks for creating PHP based web apps and APIs, and we were expecting some out of the box support for these in swagger but couldn’t find any. Anyway, we found Swagger UI and Swagger Specification very user-friendly and went on to write the specification manually for our API.

Installation

You can easily install Swagger UI by either downloading or cloning the repo. After that, just open “./dist/index.html” in your browser. Learn more about customization here .

Specification

Swagger specification consists of a YAML or JSON file. Swagger Editor ( a context aware Swagger specification editor) can certainly help you in the process but you can also use the text editor of your choice.  Here is a sample of the YAML file

swagger: '2.0'  
info:  
  title: Cloudways API  
  description: Move your app forward with the Cloudways API  
  version: "1.0.0"  
host:  cloudways.com
schemes:  
  - http  
basePath: /api/v1  
produces:  
  - application/json  
tags:  
- name: "User"  
- name: "Authentication"  
  description: "API Authentication related calls"  
paths:  
  /auth/login:  
    post:  
      summary: Login user   
      description:   
      tags:  
        - Authentication  
      parameters:  
        - $ref: 'params.yaml#/EmailPost'  
        - $ref: 'params.yaml#/PasswordPost'  
          
  /user:  
    post:  
      summary: Create a new user   
      description:   
      tags:  
        - User  
      parameters:  
        - $ref: 'params.yaml#/NamePost'  
        - $ref: 'params.yaml#/EmailPost'  
        - $ref: 'params.yaml#/PasswordPost'  
      responses:  
            200:  
              $ref: 'responses.yaml#/BasicSuccess'    
  /user/{id}:  
    post:  
      summary: update a user  
      tags:  
        - User  
      parameters:  
        - name: id  
          in: path  
          required: true  
          type: integer            
        - $ref: 'params.yaml#/NamePost'          
      responses:  
        200:  
          description: OK  
  
  /user/forgotPassword:  
    post:  
      summary: forgot password  
      description:   
      tags:  
        - User          
      parameters:  
        - $ref: 'params.yaml#/EmailPost'  
      responses:  
            200:  
              $ref: 'responses.yaml#/BasicSuccess'        
                
    

As you can see, we can re-use parts of the specification using the $ref property. Also the specification can be broken in multiple files as we use few definitions defined in a separate files (params.yaml and responses.yaml).

A excerpt from “params.yaml”

NamePost:  
    name: name  
    in: formData  
    description: description  
    type: string      
PasswordPost:  
    name: password  
    in: formData  
    required: true  
    type: string      
EmailPost:  
    name: email  
    in: formData  
    description: description  
    type: string

Final output would look like this.

A few Tips to get you going

Swagger UI is a very active project and it’s highly recommended to keep updating your build of it. But there is a caveat (as per our experience), that some minor feature may break in a certain build.

A few times you may experience that recent changes in your specification file are not reflecting in UI. This may be a caching issue, so make sure to hard-reload the page so that a fresh copy of your specification file is fetched.

To experience Swagger in action, check out Cloudways Laravel Hosting. Launch your free trial today.

Share your opinion in the comment section. COMMENT NOW

Share This Article

Launch Laravel apps with 1-Click Install. Painless Server Management

Deploy your apps on optimized Laravel hosting servers.

Najmus Saqib

Najmus Saqib is currently working as Senior Software Engineer at Cloudways. He specializes in PHP, Python, and Google App Engine.

Get Our Newsletter
Be the first to get the latest updates and tutorials.

Do you like what you read?

Get the Latest Updates

Share Your Feedback

Please insert Content

Thank you for your feedback!