社内勉強会で Swagger を紹介したときの資料です． http://kakakakakku.hatenablog.com/entry/2015/12/04/164355

1. Swagger 入門
2015-12-04
社内勉強会
@kakakakakku

3. Agenda
• Swagger とは
• Swagger の流行
• Swagger のツール群
• Swagger を試してみた 1 (トップダウンアプローチ)
• Swagger を試してみた 2 (ボトムアップアプローチ)

4. Swagger とは
• REST API ドキュメントフレームワーク
• 開発者もコンピューターも Readable
• 要するに JavaDoc 的な？w
• 違う！
• API を叩けるしドキュメントの枠を超えてる

5. Swagger とは
• 定義を JSON or YAML で書く
• Swagger Specification と呼ばれる
• 結構複雑

6. 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'

7. Swagger とは
• SORACOM API で既に稼働してる例もある
https://dev.soracom.io/jp/docs/api/

8. Swagger の流行
• Open API Initiative による標準化
• Google, IBM, Microsoft も名を連ねる

9. Swagger のツール群
• Swagger Core
• Swagger Codegen
• Swagger UI
• Swagger Editor
• Integrations
• Commercial Tools

10. 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

11. Swagger を試してみた 1
• トップダウンアプローチ
• Swagger Editor で Swagger Specification を書く
• Sinatra で簡易的な API を実装する
• Swagger UI で API を叩く
DEMO

12. Swagger を試してみた 1

13. Swagger を試してみた 1

14. Swagger を試してみた 2
• ボトムアップアプローチ
• FuelPHP に Swagger Annotation を書く
• swagger-php で Swagger Specification を生成する
• Swagger UI で API を叩く
DEMO

15. Swagger を試してみた 2
/**
* @SWGSwagger(
* schemes={"http"},
* host="192.168.33.22",
* basePath="/api/v1",
* @SWGInfo(
* version="1.0.0",
* title="Swagger Sample",
* description="This is a documents for swagger sample server.",
* @SWGContact(
* email="swagger@example.com"
* ),
* @SWGLicense(
* name="Apache 2.0",
* url="http://www.apache.org/licenses/LICENSE-2.0.html"
* )
* ),
* @SWGExternalDocumentation(
* description="Find out more about Swagger",
* url="http://swagger.io"
* )
* )
*/

16. Swagger を試してみた 2
/**
* @SWGGet(
* path="/projects",
* summary="list projects",
* tags={"project"},
* description="list projects",
* @SWGResponse(
* response=200,
* description="A list with projects"
* ),
* @SWGResponse(
* response="400",
* description="Invalid tag value",
* )
* )
*/

17. Enjoy Swagger !!!