Swaggerを利用した新規サービス開発

© Recochoku Co.,Ltd. Proprietary and Conﬁdential
2017/02/07
Swaggerを利用した
新規サービス開発
株式会社レコチョク
事業システム推進部ミュージックアーキテクトグループ
松木　佑徒

© Recochoku Co.,Ltd. Proprietary and Conﬁdential 2017/02/07
自己紹介
2
職業：フルスタックエンジニア(自称)
言語：C# (2008~2010) -> Java (2011~2015) -> Python (2016~)
趣味：ドラム / ジャグリング
Yuto Matsuki @yustam_jp id:yustam
2008: 某SIerにてシステムエンジニアとして色々な現場で仕事をする
2014: 株式会社レコチョクに転職
2014-2015: レコチョクの楽曲DB周辺のバッチなどをAWS環境上に再構築
2016-: 新サービスWIZYの開発リーダーとしてWebの開発に携わる
最近は研究開発的な事もしています。

レコチョクについて
3
https://eggs.mu http://playpass.jp
2015/02サービス開始 2016/03サービス開始

WIZYについて
4
2016/08サービス開始
https://wizy.jp

WIZYのシステム構成
5

WIZYを支える技術
6

Swagger
7

Swaggerを採用した経緯①
8
• re:Invent 2015 Bootcampで初めてSwaggerに触れる
• Swagger Api Gateway Importerを使用したハンズオン
• 用意されたSpecを利用してツールでAPI Gatewayにデ
プロイするというもの
• サーバレスという概念が出て来て間もない頃で非常に
画期的な印象

Swaggerを採用した経緯②
9
• 2015年末新規サービス開発のプロジェクトが始まる
• はじめてフロントのシステムを担当することに
• 最初のプロトタイプ開発は１人で
• 仕様書はExcelなどで書きたくない
• 書くならコードの自動生成/再利用性のあるもの
• 個人的にRAMLを使ったことがあったが
• CodeGeneratorがPythonに対応している
• Open API Initiativeが立ち上がりSwaggerを推し始めた

Swaggerを採用した経緯 ③使ってみる
10
• 簡単なSwaggerSpecをYAMLで作成
/projects/{project_id}:
get:
summary: プロジェクト取得
tags:
- Project
parameters:
- name: project_id
in: path
description: プロジェクトID
required: true
type: integer
responses:
200:
description: プロジェクト
schema:
$ref: '#/definitions/project'
project:
type: object
properties:
id:
type: integer
user_id:
type: integer
description: ユーザID
...
paths: definitions:

11
• CodeGeneratorでPythonクライアントを生成
• definitionで定義したオブジェクトをそのままJSON化
• レスポンスはdefinitionsのオブジェクトで受け取れる
import swagger_client as sw
project_api = sw.ProjectApi(api_client=api)
project = project_api.projects_project_id_get(project_id)
print(type(project))
print(type(project.end_time))
<class 'swagger_client.models.project.Project'>
<class 'datetime.datetime'>

12
• JSON Web Tokenを利用した認証
ApiKey:
type: apiKey
name: Authorization
in: header
securityDefinitions:
/authenticate:
post:
summary: 認証API
tags:
- Auth
parameters:
- name: authenticate
in: body
required: true
schema:
$ref: '#/definitions/authenticate'
responses:
200:
description: トークン
schema:
$ref: '#/definitions/token'
paths:
authenticate:
type: object
properties:
key:
type: string
description: 認証キー
secret:
type: string
format: string
description: 認証シークレット
token:
type: object
properties:
access_token:
type: string
description: 認証トークン
definitions:

13
• JSON Web Tokenを使用した認証を採用
import swagger_client as sw
auth_api = sw.AuthApi(sw.ApiClient(API_HOST))
auth = sw.Authenticate(key='user',secret='hogehoge')
resp = auth_api.authenticate_post(authenticate=auth)
api = sw.ApiClient(host=API_HOST, header_name='Authorization',
header_value='JWT %s' % resp.access_token)
project_api = sw.ProjectApi(api_client=api)
project = project_api.projects_project_id_get(project_id)
curl-X POST -d '{"key":"user","secret":"hogehoge"}' http://${API_HOST}/authenticate
curl -X GET -H "Authorization: JWT ${JWT_TOKEN}" http://${API_HOST}/projects/${PROJECT_ID}

WIZYにおけるSwagger
14
• Swaggerの仕様バージョン2.0
• 開発言語はPython
• API側のフレームワークはFlask
• APIの認証はFlask-JWTを使用したJWTトークン認証
• 2017年2月時点でAPI数は 63 (pathベースで38)

Swagger Code Generator
15
YAMLで仕様を管理。YAMLから生成
https://github.com/swagger-api/swagger-codegen
html
python
get:
tags:
- Project
parameters:
- name: project_id
in: path
required: true
type: integer
responses:
200:
schema:

WIZYの開発手法
16
1. 機能要件に従ってテーブル定義等の仕様を決める
2. フロントの要件に従ってAPI仕様をSwagger Specで書く
3. Swagger Specに従ってAPIを実装
4. Swagger Code Generatorでクライアントを生成
5. 生成したクライアントを使用してフロントのアプリを実装
web api
client
cache database
spec

Swaggerを使って良かったこと(開発)
17
APIの仕様レビューがYAMLファイル上で行える
• diffで比較できるのでレビュー漏れが無い
• JSONよりYAMLの方が書き方に個人差が出ないのでオススメ

18
書式が決まっているのでAPIに必要な情報について曖昧さがない
実装前にある程度挙動を確認できるので手戻りが防げる
APIの開発者とクライアント側の開発者が並行で作業できる
他との矛盾/命名規則の違反などを発見しやすい
他のpaths/definitionsを再利用できる
get:
tags:
- Project
parameters:
- name: project_id
in: path
required: true
type: integer
responses:
200:
schema:

19
そのままコードになるのでレビューした内容とコードに差がない
ドキュメントにもなるのでコードとドキュメントの乖離がない

Swaggerを使って良かったこと(運用)
20
Web/APIを分離してバージョン管理しやすくなる
SwaggerSpecに変更がある場合のみAPI仕様に変更がある
swaggerのtags
webのtags apiのtags× ×

21
Blue-Green Deploymentにより無停止でバージョンアップ可能に
本番環境ELB
API-ELB
API v1.0
API v1.1ステージ環境ELB
Web v2.0
Web v2.1
しかしAPIに互換性がない場合は並行稼動できない…

22
APIのインタフェース仕様の変更が一目でわかるので
前のバージョンと互換性があるかの判断が簡単になる
→ pathの追加だけであれば問題ない。など
差分がない場合は仕様に変更がないことが保証されるが
ソート順などは表現されないのでインタフェース以外の
修正は個別で判断する必要がある

「operationId」の定義は必要か
23
https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-7-documentation/
paths:
/persons:
parameters:
- $ref: '#/parameters/userAgent'
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
operationId: searchUsers
[main] WARN io.swagger.codegen.DefaultCodegen - Empty operationId found
for path: post /projects/{project_id}/items. Renamed to auto-generated
operationId: projectsProject_idItemsPost
「operationId」はAPI単位にユニークな名前をつけるもの
書かないとCodeGeneratorに怒られます。。

Swaggerの使い方について今後の課題①
24
# operationId未指定の場合
projects = project_api.projects_get(limit=10)
# operationIdを指定した場合
projects = project_api.search_projects(limit=10)
ルールを作るとしたら
• 「GET /XXXs」=>「search_XXXs」
• 「GET /XXXs/{YYY}」 => 「get_XXX_by_YYY」
• 変えたい場合もある。POST/PUT場合はどうする。。？
APIのpathとは別でルールを考える必要がありそう
Pythonクライアントの場合は自動でメソッド名が決まる

© Recochoku Co.,Ltd. Proprietary and Conﬁdential 2017/02/07 25
• OpenAPI 3.0 への移行
• 全体の99％を占めるpaths/definitionsに大きな変更なし？
• definitionsはcomponentsの配下に移動
• pathsはそのままに見えます…
https://www.openapis.org/news/blogs/2016/10/tdc-structural-improvements-explaining-30-spec-part-2
今後の課題(3.0対応)

Swaggerを利用した新規サービス開発

Recommended

Recommended

More Related Content

What's hot

What's hot (19)

Viewers also liked

Viewers also liked (20)

Similar to Swaggerを利用した新規サービス開発

Similar to Swaggerを利用した新規サービス開発 (20)

More from recotech

More from recotech (8)

Recently uploaded

Recently uploaded (14)

Swaggerを利用した新規サービス開発