Webシステムの開発にはAPIドキュメント作成が必ず付いてきます。システム改修が加えられてもAPIドキュメントが古いままで更新されてなかったり（更新し忘れていたり）した経験はありませんか？ドキュメントの更新を忘れがちな方のために、ソースコード上でAPIドキュメントも管理できるドキュメンテーションツール『Swagger』についてお話しいたします。

1. Swaggerで簡単
APIドキュメント作成
2016.8.30 Tue
⼩小⾕谷松 丈樹
出張！雲勉 in Tokyo
勉強会／開発者向け

2. ⾃自⼰己紹介

3. ⾃自⼰己紹介（軽くね、かる〜～く
• アイレット cloudpack開発事業部
• セクションリーダー ⼩小⾕谷松丈樹（おやまつ）
• 主に使⽤用している⾔言語

4. ⾃自⼰己紹介（軽くね、かる〜～く
• アイレット cloudpack開発事業部
• セクションリーダー ⼩小⾕谷松丈樹（おやまつ）
• 主に使⽤用している⾔言語
• ⽇日本語
• ベトナム⼈人教育セクション
• チームの⽇日本⼈人不不⾜足が深刻化
• PHP歴5年年
• リーダー歴2ヶ⽉月
• 最近プロマネメインに転向

5. Swaggerとは

6. Swaggerとは
• ソースコード内のアノテーションから
APIドキュメントを作れる
• アノテーションの形式化
• Swagger-‐‑‒UIで実際にAPIリクエストを投げられる
• つまり、何がいいのさ

7. ソースコードのコメント品質向上
• たまに⾒見見るこんなやつも
• こんなふうに
• なるといいな（遠い⽬目
/**
*
この関数はいつか消す
*
例外は握りつぶす
*/
/**
*
このメソッドのリクエストURLはこれで
*
リクエストパラメータはこれが必須で
*
リターンはこんな形で
*
例外発生時はこうなって...
*/

8. 仕事の役割分担
• APIドキュメントをまとめるのはPMの仕事？
• 😩.oO（こういう のとか
こういう アイコンって重いんだよなぁ
• ソースコード＝APIドキュメント
• これならプログラマの領領分
• PM「しめしめ」
• ソースコードと同時にAPIドキュメントも更更新
• 改修を加え続ける案件でもドキュメントが常に最新

9. 開発者に優しい
• Swagger-‐‑‒UI
• 実際にAPIを叩けるドキュメント
• 単体テストが楽
• APIを使う側も分かりやすい
Swagger-­‐UIデモサイト h1p://petstore.swagger.io/

10. Swagger のいいところ
• ソースコードのコメント品質向上
• PMの仕事をプログラマに渡せる
• 重いアプリケーションを開かなくていい
• 仕様変更更が多くてもドキュメントが追いてけぼりにならない
• APIの単体テストが楽
• APIリクエストを確認できる
• などなど

11. Swagger って

12. で、どう書くの？
Swagger-‐‑‒PHP v2.x

13. アプリケーション全体の説明
/**
*
@SWGSwagger(
*
schemes={"h-p"},
*
host="localhost",
*
basePath="/",
*
@SWGInfo(
*
version="1.0.0",
*
>tle="出張！雲勉 in
Tokyo登壇デモAPI",
*
descrip>on="あんなことやこんなことをするAPI"
*
)
*
)
*/
• @SWGInfo

14. モデルの定義
/**
*
@SWGDefini2on(
*
defini>on="user",
*
@SWGProperty(property="user_id",
type="integer",
descrip>on="ユーザID"),
*
@SWGProperty(property="name",
type="string",
descrip>on="ユーザ名"),
*
@SWGProperty(property="job",
type="string",
descrip>on="仕事")
*
)
*/
• @SWGDefini2on

15. モデルの定義（こう書いても良良いかも
/**
*
@SWGDefini>on(defini>on="user")
*/
class
User
extends
Model
{
/**
*
@SWGProperty(property="user_id”,
type="integer",
descrip>on="ユーザID")
*/
public
$user_id;
/**
*
@SWGProperty(property="name",
type="string",
descrip>on="ユーザ名")
*/
public
$name;
/**
*
@SWGProperty(property="job”,
type="string",
descrip>on="仕事")
*/
public
$job;
• @SWGDefini2on
同じ！

16. APIの定義
/**
*
@SWGGet(
*
path=“/user”,
*
summary=“ユーザ情報取得”,
*
descrip>on=“コンストラクタで設定されたユーザ情報の取得",
*
produces={"applica>on/json","applica>on/xml"},
*
@SWGResponse(
*
response=200,
*
descrip>on="successful
opera>on",
*
@SWGSchema(ref="#/defini>ons/user")
*
)
*
)
*/
• @SWGGet,
@SWGPost,
@SWGPut,
.....

17. アノテーション書いてどうすんの？

18. Swaggervel

19. Swaggervel
• PHPフレームワーク Laravel 向けに作られたパッケージ
• Swagger-‐‑‒php と Swagger-‐‑‒ui を内包
• composer require jlapp/swaggervel:master-‐‑‒dev
h1ps://laravel-­‐news.com/2015/01/swagger-­‐laravel/

20. Swaggervel
• Installation
• Add Jlapp＼Swaggervel＼SwaggervelServiceProvider to
your providers array in app/config/app.php
• Run php artisan vendor:publish to push swagger-‐‑‒ui to
your public folder
• ↑コマンドを叩くと
public/下に
ファイルができる

21. Swaggervel
• JSON を吐き出すコマンド
$ vendor/bin/swagger app/Http/Controllers -‐‑‒o public/docs
• public/docs/swagger.json
{
"swagger":
"2.0",
"info":
{
"Ntle":
"u51fau5f35uff01u96f2ufa33
in
Tokyou767bu58c7u30c7u30e2API",
"descripNon":
"u3042u3093u306au3053u3068u3084u3053u3093u306a...",
"version":
"1.0.0"
},
"host":
"localhost",
"basePath":
"/",
"schemes":
[
"h1p"
],
"paths":
{
"/user":
{
"get":
{
...

22. Swaggervel
• http://SERVER_̲NAME/api/docs にアクセス
• http://SERVER_̲NAME/docs/swagger.json を読みこませる
user_id
:
int
name
:
string
job
:
string
→
定義した通り！

23. Swaggervel
• http://SERVER_̲NAME/api/docs にアクセス
• http://SERVER_̲NAME/docs/swagger.json を読みこませる
user_id
:
int
name
:
string
job
:
string
→
定義した通り！

24. 動く！

25. Swagger って

26. まとめ

27. Swaggerを使う流流れ
• プログラム+Swagger定義を書く
→ アノテーションからJSONを作るコマンドを実⾏行行
→ ローカル環境のSwagger-‐‑‒UIで動作確認
→ 問題無ければcommit
• サーバ上のSwagger-‐‑‒UIでQAテスト
• API使う側もSwagger-‐‑‒UIを⾒見見ながらリクエストを作成

28. 本⽇日のまとめ（軽くね、かる〜～く
• Swagger って、ええやん！
• ソースコードの品質向上
• PMが楽できる ←最⾼高！
• インタラクティブAPIドキュメント ←たのしい！

29. 本⽇日のまとめ（軽くね、かる〜～く
• Swagger って、ええやん！
• ソースコードの品質向上
• PMが楽できる ←最⾼高！
• インタラクティブAPIドキュメント ←たのしい！
• Swaggerで楽したいエンジニア、来たれ！
• サーバーサイド・フロントエンドエンジニア、マネージャー様！
cloudpackでは、
開発エンジニア／インフラエンジニア／デザイナー 鋭意募集中！
http://cloudpack.jp/recruit