Upload
mesh-korea
View
342
Download
0
Tags:
Embed Size (px)
DESCRIPTION
-Mesh Korea.Jongsun.Yi
Citation preview
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