quick run in with swagger

a giant pile of money in the bank.

Let me give you …

You need a way to access it.

Apache Thrift

• Thrift Interface Description Language to define a specification

• A transport layer to handle data serialisation and transfer

• Code generators to create interface that can be used to bind concrete implementations of API providers/consumers

IDLInterface

DescriptionLanguage

Server Client

Swagger• Swagger Spec defines how APIs

should be comprehensively described and understood using a JSON format.

• Swagger JSON

• hand written

• statically generated

• dynamically generated

• generated from traffic logs

• served anywhere

Swagger Spec

Swagger Core

Swagger JS Swagger

Codegen

Swagger UI

Swagger node-

express

Swagger PHP

Swaggervel

Raw 2 Swagger

Swagger

Swagger Spec

Swagger Core

Swagger JS Swagger

Codegen

Swagger UI

Swagger node-

express

Swagger PHP

Swaggervel

Raw 2 Swagger

• Swagger UI to present API in a human-friendly format and easily interface and test.

• Since almost all of our servers are written in PHP, naturally Swagger PHP.

Swagger PHP• Composer package

• Use annotations to specify models and API methods (http://zircote.com/swagger-php/annotations.html)

• Statically generate Swagger JSON php swagger.phar /projects/my_project -o /var/html/swagger-docs

• or, generate dynamically use Swagger\Swagger;$swagger = new Swagger('/projects/my_project');header('Content-Type: application/json');echo $swagger->getResource('/pet', array('output' => 'json'));

/** * @SWG\Model(id="Company", required="['id', 'status']") */class Company{ /** * @SWG\Property(name="id",type="string") */ public $id; /** * @SWG\Property( * name="status",type="string", * enum="['normal', 'closed', 'overburdened']", * description="operational status of the company") */ public $status; }

/** * @SWG\Resource( * apiVersion="0.1", * swaggerVersion="1.2", * resourcePath="/company", * basePath="http://jongsunyi.meshkorea.lab/bootake/public/callback/mesh" * ) */class Callback_Mesh_Company_Controller extends Base_Controller{ /** * * @SWG\Api( * path="/company/{companyId}", * description="Operations about Companies", * @SWG\Operation( * method="POST", * summary="Update Company", * notes="Updates information on the ID company on the server", * type="boolean", * nickname="updateCompany", * @SWG\ResponseMessage(code=404, message="Company not found"), * @SWG\Parameter( * name="companyId", * description="ID of Company that needs to be updated", * paramType="path", * required=true, * allowMultiple=false, * type="string" * ), * @SWG\Parameter( * name="company", * description="model of Company that needs to be applied", * paramType="body", * required=true, * allowMultiple=false, * type="Company" * ) * ), * ) */ public function action_index($companyId = '') { // … }

jongsunyi@mesh-rnd $ php vendor/zircote/swagger-php/swagger.phar application/controllers/callback -o swagger-docs

Swagger-PHP 0.9.6 ----------------- Created swagger-docs/api-docs.json Created swagger-docs/index.php Created swagger-docs/company.json

Static Generation

Route::any('callback/mesh/api-doc', array('uses' => 'callback.mesh@index')); Route::any('callback/mesh/api-doc/(:any)', array('uses' => 'callback.mesh@swagger'));

use Swagger\Swagger; class Callback_Mesh_Controller extends Base_Controller{ /** * @var Swagger */ protected $swagger; public function __construct() { $this->swagger = new Swagger(array(path('app') . '/controllers/callback'), array(path('composer'))); } public function get_index() { $response = $this->swagger->getResourceList(array('output' => 'array')); return Response::json($response); } public function get_swagger($resource = '') { $response = @$this->swagger->getResource("/$resource", array('output' => 'array')); if (!$response) { \Log::debug("Swagger resource $resource not found."); return Response::error('404'); }

Dynamic

Swagger PHP

• Using code annotation to make it easier to maintain.

• Dynamically generating Swagger JSON can be costly if project that must be parsed is large.

Swagger UI

Anyone who says that they're great at communicating but 'people are bad at listening' is confused about how communication works.

https://github.com/swagger-api/swagger-ui Point it at a Swagger resource listing

A lot morereally

https://github.com/swagger-api/swagger-spec