Swaggerと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

4. 本日のトピック

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

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

7. 問題意識

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

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

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

11. そこで Swagger!

12. Swaggerとは

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

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

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

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

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

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

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

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

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

22. 使ってみる(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));

23. 僕とSwagger

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

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

26. サンプルコード : 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}}})

27. サンプルコード : 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の実装

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

29. どうですか Swagger!

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