More Related Content Similar to SwaggerとAPIのデザイン (20) More from Kazuhiro Hara (20) 3. Clojure / ClojureScript で
Electronアプリケーションを
作るためのスタートキット / プラットホーム
● オープンソースにてGitHubにて公開
● MITライセンス
● 現在のスター数 : 289
http://descjop.org/
+9 Point up
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.
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
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の実装
