swagger 入門
TRANSCRIPT
Swagger 入門2015-12-04 社内勉強会 @kakakakakku
Agenda
• Swagger とは
• Swagger の流行
• Swagger のツール群
• Swagger を試してみた 1 (トップダウンアプローチ)
• Swagger を試してみた 2 (ボトムアップアプローチ)
Swagger とは
• REST API ドキュメントフレームワーク
• 開発者もコンピューターも Readable
• 要するに JavaDoc 的な？w
• 違う！
• API を叩けるしドキュメントの枠を超えてる
Swagger とは
• 定義を JSON or YAML で書く
• Swagger Specification と呼ばれる
• 結構複雑
Swagger とはswagger: '2.0' info: title: Sinatra Swagger Sample API description: This is my Sinatra Swagger Sample API version: 1.0.0 host: localhost:4567 schemes: - http basePath: / produces: - application/json paths: /users: get: summary: All users description: All users responses: '200': description: An array of users schema: type: array items: $ref: '#/definitions/User'
/users/{userId}: get: summary: Find user description: Find user parameters: - name: userId in: path description: User id required: true type: integer format: int64 responses: '200': description: users schema: type: array items: $ref: '#/definitions/User'
Swagger とは
• SORACOM API で既に稼働してる例もある
https://dev.soracom.io/jp/docs/api/
Swagger の流行
• Open API Initiative による標準化
• Google, IBM, Microsoft も名を連ねる
Swagger のツール群
• Swagger Core
• Swagger Codegen
• Swagger UI
• Swagger Editor
• Integrations
• Commercial Tools
Swagger のツール群
Export
Swagger Editor
Swagger UI
Swagger Specification
App
Swagger Codegen
Commercial Tools
Import
JSON or YAML
swagger-php
http://swagger.io/tools/
Import
API Gateway
Swagger を試してみた 1
• トップダウンアプローチ
• Swagger Editor で Swagger Specification を書く
• Sinatra で簡易的な API を実装する
• Swagger UI で API を叩く
DEMO
Swagger を試してみた 1
Swagger を試してみた 1
Swagger を試してみた 2
• ボトムアップアプローチ
• FuelPHP に Swagger Annotation を書く
• swagger-php で Swagger Specification を生成する
• Swagger UI で API を叩く
DEMO
Swagger を試してみた 2/** * @SWG\Swagger( * schemes={"http"}, * host="192.168.33.22", * basePath="/api/v1", * @SWG\Info( * version="1.0.0", * title="Swagger Sample", * description="This is a documents for swagger sample server.", * @SWG\Contact( * email="[email protected]" * ), * @SWG\License( * name="Apache 2.0", * url="http://www.apache.org/licenses/LICENSE-2.0.html" * ) * ), * @SWG\ExternalDocumentation( * description="Find out more about Swagger", * url="http://swagger.io" * ) * ) */
Swagger を試してみた 2
/** * @SWG\Get( * path="/projects", * summary="list projects", * tags={"project"}, * description="list projects", * @SWG\Response( * response=200, * description="A list with projects" * ), * @SWG\Response( * response="400", * description="Invalid tag value", * ) * ) */
Enjoy Swagger !!!