Swagger is a powerful tool to generate interactive documentation for your RESTful API using phpdoc annotations
Installation
- Add the following dependency in the composer.json file
"require": {
"zircote/swagger-php": "*",
}
}
- Run the following command to install the package
composer update
- Add annotations to your php file
PushController.php
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use App\Http\Requests;
use App\Http\Controllers\Controller;
use App\Jobs\SendReminderEmail;
use App\Jobs\SendWelcomeEmail;
use App\Utilities\AuditTrail;
class PushController extends Controller
{
public function __construct(AuditTrail $AuditTrail){
$this->objAuditTrail = $AuditTrail;
}
/**
* @SWG\Info(title="Halo", version="1.0")
* @SWG\Get(
* path="/push",
* tags={"Queue"},
* @SWG\Response(response="200", description="Push job to the queue")
* )
*/
public function push(){
$customerName = 'Jefferey Turner';
$job = (new SendWelcomeEmail($customerName));
$this->dispatch($job);
$job->delete();
$customerName = 'Fay Padberg';
$job = (new SendReminderEmail($customerName));
$this->dispatch($job);
$job->delete();
$this->objAuditTrail->logData('Job push controller','Job pushed onto queue');
return 'Email pushed onto queue';
}
}
|
|---|
- Generate the swagger documentation
- From php
$swagger = \Swagger\scan(<Project Path>);
header('Content-Type: application/json');
echo $swagger;
header('Content-Type: application/json');
echo $swagger;
- From the command line.Go to vendor/bin folder and issue the following command
swagger <Project directory> --output <Output directory>
Eg: swagger ..\..\\app --output ..\..\public\api\
Swagger will create the json file (swagger.json) and store it in public/api folder.
swagger.json
{
"swagger": "2.0",
"info": {
"title": "Halo",
"version": "1.0"
},
"paths": {
"/push": {
"get": {
"tags": [
"Queue"
],
"responses": {
"200": {
"description": "Push job to the queue"
}
}
}
}
},
"definitions": {}
}
|
|---|
View the API resources withe the help of swagger UI
- Download the Swagger UI from https://github.com/swagger-api/swagger-ui and extract the files.
- Create the folder (swagger) folder in resources/view folder
- Copy the files from dist folder and put it in swagger folder.
- Copy the js,css,images and put it in public folder
- Change the index.html file to index.blade.php
- Make the following changes in index.blade.php.(Use blade template directives)
<link href="{{asset('css/typography.css')}}" media='screen' rel='stylesheet' type='text/css'/>
<link href="{{asset('css/reset.css')}}" media='screen' rel='stylesheet' type='text/css'/>
<link href="{{asset('css/screen.css')}}" media='screen' rel='stylesheet' type='text/css'/>
<link href="{{asset('css/reset.css')}}" media='print' rel='stylesheet' type='text/css'/>
<link href="{{asset('css/print.css')}}" media='print' rel='stylesheet' type='text/css'/>
<script src="{{asset('lib/jquery-1.8.0.min.js')}}" type='text/javascript'></script>
<script src="{{asset('lib/jquery.slideto.min.js')}}" type='text/javascript'></script>
<script src="{{asset('lib/jquery.wiggle.min.js')}}" type='text/javascript'></script>
<script src="{{asset('lib/handlebars-2.0.0.js')}}" type='text/javascript'></script>
<script src="{{asset('lib/js-yaml.min.js')}}" type='text/javascript'></script>
<script src="{{asset('lib/lodash.min.js')}}" type='text/javascript'></script>
<script src="{{asset('lib/backbone-min.js')}}" type='text/javascript'></script>
<script src="{{asset('js/swagger-ui.js')}}" type='text/javascript'></script>
<script src="{{asset('lib/highlight.7.3.pack.js')}}" type='text/javascript'></script>
<script src="{{asset('lib/jsoneditor.min.js')}}" type='text/javascript'></script>
<script src="{{asset('lib/marked.js')}}" type='text/javascript'></script>
<script src="{{asset('lib/swagger-oauth.js')}}" type='text/javascript'></script>
|
|---|
- Change the url link in the index.blade.php
- Create the controller to handle the request.
SwaggerController.php
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use App\Http\Requests;
use App\Http\Controllers\Controller;
class SwaggerController extends Controller
{
public function index(){
return view('swagger.index');
}
}
|
|---|
- Update the routes.php
Route::get('swagger', 'SwaggerController@index');
- Link to view the API documentation
http://<server>/swagger [http://api.int.halo.devthing.link/swagger]
No comments:
Post a Comment