Let's Swagger
Let's Swagger
社内勉強会で使用した資料をはてな用にアレンジしたものです。
Goals
- Swaggerって何か聞かれて答えられる程度の知識をみにつける
- 具体的に何ができるのか、HowとWhatを知る
つゆばらい
- 序盤英語です
- 翻訳が面倒でした。ごめんなさい
- 英語見ると蕁麻疹出ちゃう人はよそ見しててください
- でも、英語できないとエンジニア人生かなり辛いです
Swaggerを使う準備として調べてみたことを発表しています
ってことは、私自身の実績は
ないですありませんでしたでも、参画中のプロジェクトでは使われています使ってると言える程度に関わるようになりました
自分自身のために勉強したことを発表用に仕立て直してます
- そのため、興味の対象が偏ってるかもしれません
What's Swagger ?
Ansower quoted from official Site
The World's most popular Api tooling.
Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.
構成要素
- DESIGN : Swagger Editor
- BUILD : Swagger Codegen
- DOCUMENT : Swagger UI
DESIGN (with Swagger Editor)
Design new APIs, or edit existing ones, in a powerful editor which visually renders your OAS/Swagger definition with concise, real time feedback and error handling.
- 要はAPIの設計をエディター上でパワフルにやれるって書いてある
demo -> https://editor.swagger.io
BUILD (with Swagger Codegen)
Quickly build APIs by turning your OAS/Swagger definition into code, generating server stubs and client libraries in over 40 different languages, allowing for development and prototyping.
- 要約すると定義ファイルからコード生成できるよって書いてある
# demo $ swagger-codegen generate \ -i http://petstore.swagger.io/v2/swagger.json \ -l nodejs-server \ -o ./ist-swagger-demo $ cd ist-swagger-demo $ tree . . ├── README.md ├── api │ └── swagger.yaml ├── controllers │ ├── Pet.js │ ├── Store.js │ └── User.js ├── index.js ├── package.json ├── service │ ├── PetService.js │ ├── StoreService.js │ └── UserService.js └── utils └── writer.js $ npm install $ node .
DOCUMENT (with Swagger UI)
Visualize your API's resources from its OAS/Swagger definition and generate beautiful, interactive documentation that can be hosted in any environment, allowing your end consumers to easily get started with your API.
- 要約すると定義ファイルから綺麗な仕様書生成するよって書いてある
# Continuing the previous, execute followings $ npm install $ node . # then, go to http://localhost:8080/docs/
なぜSwaggerを使うのか
その1:API仕様書を元にコード化できるから
- YAML/JSONで仕様書が書ける
- Good by Excel !
- API定義ファイルから
- 多数の言語のクライアントコードなどが生成できる
- サーバもさくっと作れる
- mockとして使うもよし、ベースに使ってもよし
- トップダウン形式というらしい
その2:コードからでもAPI仕様書の自動生成ができるから
- Spring, JAX-RS, Servletに対応
- swagger-coreのGitに明記されている
- 既存ソースにアノテーション貼って、ちょっと設定用コードかくだけで動く
- 途中からでも導入できる!(と期待している)
- ボトムアップ形式というらしい
その3:デファクタスタンダードだから
- まだなってない気がするけど、たぶんなる、たぶん…。
- フォーマットについて、一度学習すれば他の現場他の案件でも同じ
- そのフォーマットを見慣れることになるので、見落としが減る
今回はボトムアップ形式について見てみましょう
- サンプルアプリを作ってみた
- SpringFoxを適用して、Swagger Spec自動生成
- からのSwagger-UIで仕様書の出来栄えを見ていく
デモ用サンプルアプリ
git clone https://github.com/kogayushi/swagger-demo.git
どんなアプリか
Identity Manager
- ID認証して認証情報を返すだけの簡単なお仕事
Framework
- Spring Boot
- Spring MVC
Protocol
- RESTful API
とりあえず、完成したSwagger-UIを見てください
$ cd swagger-demo $ ./gradlew bootRun # go to http://localhost:8080/swagger-ui.html
git commit logを追います
Swagger用アノテーションなしのプレーンな状態からアノテーションを張っていくごとに徐々に育っていく様子にご注目ください
https://github.com/kogayushi/swagger-demo
Step 1
- Apply Spring Fox for swagger
変更点
Swagger UI
ダメなところ
- リクエストパラメーターがわかりにくい
- レスポンスパラメーターがわかりにくい
- formパラメーターでは具体的に何を送るべきかわからない 4.サンプル値がない 5.model見ると全部optionalってありえない 6.定義してない4XX Http Statusがならんでる
- 401/403は使ってない
- 5XX Http Statusがない
- ありえない
- 少なくとも予期せぬエラーで500は絶対に返すことある
Step 2
- Declare input variable as to be independen from form data
- 独立した項目として入力値を定義する
変更点
Swagger UI
Step 3
- Disable default response definition
- デフォルトレスポンスの定義を消す
変更点
Swagger UI
Step 4
- Declare proper response http status
- 返す可能性のあるHttp Statusを正しく定義する
変更点
Swagger UI
Step 5
変更点
Swagger UI
Step 6
- Add descriptive annotation of Swagger into Error response DTO classes.
- Swaggerの記述用アノテーションをエラーレスポンスのDTOクラスに付与する
変更点
Swagger UI
課題
- エラーレスポンスの例が全てのHttp Statusでおなじになってしまっている
- エラーレスポンスの定義を全てのコントローラーで定義しなければならなさそう
- メタアノテーションを作成すれば回避は可能(検証済)
終わりに
このようにアノテーションを張っていくだけで仕様書が出来上がってしまうというすぐれものです。 みなさんも、ぜひご活用ください。