![サンプルコード : 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の実装](https://image.slidesharecdn.com/okachi-170512051646/85/Swagger-API-30-320.jpg)
SwaggerとAPIのデザイン
- 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. 本日のトピック
- 7. もくじ 1. 問題意識 2. Swaggerとは 3. ExpressとSwaggerのサンプルを見てみよう 4. 僕とSwagger (Clojureベースの環境で利用しています)
- 8. 問題意識
- 10. RESTful APIのドキュメントあれこれ ● Wikiで管理 ● Word / Excelで管理 ● クラウドで同時編集可能なGoogle Docsで管理 ● リポジトリ内のドキュメント ● 何かの自動生成ツールとか
- 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.
- 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の仕様をサーバー側で実装しておくと、自動でドキュメントが生成される ○ たぶん、もっともよく使う部分 こちらもあとでデモします
- 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