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.

Laravel Swagger Restler

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: