Swaggerではじめる楽々RESTful APIデザイン&ドキュメント管理

1. SwaggerとAPIのデザイン
Swaggerではじめる楽々RESTful APIデザイン&ドキュメント管理
2017/5/12
Okachi.js vol.5
第1回

2. 出演
{:company “Greative.GK”
:name “Kazuhiro Hara”
:twitter “@kara_d”
:interest “SPA, WebVR, Clojure,
Design research”}

3. Clojure / ClojureScript で
Electronアプリケーションを
作るためのスタートキット / プラットホーム
● オープンソースにてGitHubにて公開
● MITライセンス
● 現在のスター数 : 289
http://descjop.org/
+9 Point up

5. 本日のトピック

6. SwaggerとAPIのデザイン
http://swagger.io/

7. もくじ
1. 問題意識
2. Swaggerとは
3. ExpressとSwaggerのサンプルを見てみよう
4. 僕とSwagger (Clojureベースの環境で利用しています)

8. 問題意識

9. RESTful APIのドキュメントどうしていますか？

10. RESTful APIのドキュメントあれこれ
● Wikiで管理
● Word / Excelで管理
● クラウドで同時編集可能なGoogle Docsで管理
● リポジトリ内のドキュメント
● 何かの自動生成ツールとか

11. RESTful APIのドキュメントあるある
● みんなに意見を聞く

12. そこで
Swagger!

13. Swaggerとは

15. Swagger
Swagger is a powerful open source framework backed by a large ecosystem of tools that helps you design,
build, document, and consume your RESTful APIs.

16. Swagger
Swaggerは、RESTful APIの設計、構築、文書化、および使用に役立つ、大規模なエコシステムツールを使用し
た強力なオープンソースフレームワークです。(by Google翻訳)

17. 発音
スゥァガー(YouTube調べ)

19. Swaggerでできること(1)
● Swagger Editor
○ http://swagger.io/swagger-editor/
○ APIの設計を視覚的に行うことが出来るツール
○ エディターエリアとプレビューエリアがある
あとでデモします

20. Swaggerでできること(2)
● Swagger Codegen
○ http://swagger.io/swagger-codegen/
○ Swaggerで定義した仕様からサーバー側のコードを生成する
■ API clients
● ActionScript, Bash, C# (.net 2.0, 4.0 or later), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Go, Groovy, Haskell, Java
(Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign), Node.js (ES5, ES6, AngularJS with Google Closure Compiler
annotations) Objective-C, Perl, PHP, Python, Ruby, Scala, Swift (2.x, 3.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery,
Node)
■ Server stubs
● C# (ASP.NET Core, NancyFx), Erlang, Go, Haskell, Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy),
PHP (Lumen, Slim, Silex, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Scala (Finch, Scalatra)
■ API documentation generators: HTML, Confluence Wiki
■ Others: JMeter

21. Swaggerでできること(3)
● Swagger UI
○ http://swagger.io/swagger-ui/
○ Swaggerの仕様をサーバー側で実装しておくと、自動でドキュメントが生成される
○ たぶん、もっともよく使う部分
こちらもあとでデモします

22. ExpressとSwaggerのサンプルを
見てみよう

23. サンプル使用までの流れ
swagger-node
https://github.com/swagger-api/swagger-node
を使います
テンプレートをexpress, hapi, restify, sailsから選べる
$ npm install -g swagger
$ swagger project create hello-world

24. 使ってみる(1)
まずは、Swagger Editor
$ swagger project edit

25. 使ってみる(2)
Swagger UIを試す
/app.js を変えていく。まず、ミドルウェアライブラリの読み込み
続いて、appオブジェクトにミドルウェアを指定する
サーバの起動 : http://localhost:10010/docs/
$ swagger project start
var SwaggerUi = require('swagger-tools/middleware/swagger-ui');
app.use(SwaggerUi(swaggerExpress.runner.swagger));

26. 僕とSwagger

27. Swagger UIは、様々な言語から利用できる
● Node.jsで開発している人でなくても利用できる
● 既存のアプリケーションに組み込むこともできる
● 一度仕様を作れば、万が一移植することになっても、
ドキュメント面の変更がほとんどない(出力されたものに関しては)

28. ClojureでのAPI開発に全面的に使用
● 使い道 : SPA開発のAPIデザイン & バックエンド開発
○ フロントエンドとバックエンド同時に作ったり
● compojure-apiというフレームワークでAPIを構築している
● Swaggerと統合されているのでこんなことがかんたんに出来る
○ リクエスト時のJSONの型を定義して実装にもドキュメントにも反映
○ レスポンス時のJSONの型を定義して実装にもドキュメントにも反映
○ Swaggerの仕様の基づいているので、実装しているAPIのパラメータ仕様などが
そのままドキュメントになる
○ 開発時だけSwaggerを有効にして、本番時は無効にする

29. サンプルコード : I/O周りの仕様定義
POST時のリクエストの仕様 (一部適当です)
POST時のレスポンスの仕様 (一部適当です)
(s/defschema RequestPost
"POSTのスキーマ"
{:data {:type (s/eq “markdown”)
:attributes {:markdown s/Any}}})
(s/defschema ResponsePost
"POST返り値のスキーマ"
{:data {:type (s/eq “markdown”)
(s/optional-key :errors) s/Any
:attributes {:result s/Any}}})

30. サンプルコード : APIの実装
(def kara-d-api
(api
{:swagger (if (env/dev?)
{:ui "/api-docs-markdown"
:options {:ui {:validatorUrl nil}}
:spec "/swagger-markdown.json"
:data {:info {:title "markdown API"
:description ""}
:tags [{:name "api-markdown", :description ""}]}}
nil)
:format { ... }}}
(context "/api/markdown" []
:tags ["api-markdown"]
(POST "/" request
:summary "markdown投稿"
:body [post RequestPost]
:return ResponsePost
(if-not (authenticated? request)
(bad-request (error/unauthorized config/api-type))
(ok (handler-api/post! post request))))
... 他のAPI定義
)))
Swaggerの定義メタデータ
各APIの実装

31. Swaggerいいことまとめ
● Swaggerが統合されたフレームワークであれば、実装コードにSwagger用のメタデー
タを付与するだけで、ドキュメントの構築が可能
○ 使い方は、それぞれのフレームワークのドキュメントを見よう
○ かなりの言語が対応しているはず
● 実装と仕様ドキュメントのずれがなくなる
● リポジトリで一緒に管理できる
● 動作するドキュメントとして、いろいろ試せる
● APIを設計するときに細かな仕様を考えられる
● とりあえず適当なサーバを立ち上げられる

32. どうですか
Swagger!

33. - END -
ありがとうございました
2017/5/12
Okachi.js vol.5