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.

要約すると(RESTful)APIの設計、文書化、テスト、開発を網羅した世界最大のフレームワークって書いてある

構成要素

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を使うのか

その１：API仕様書を元にコード化できるから

YAML/JSONで仕様書が書ける
- Good by Excel !
API定義ファイルから
- 多数の言語のクライアントコードなどが生成できる
- サーバもさくっと作れる
  - mockとして使うもよし、ベースに使ってもよし
トップダウン形式というらしい

その２：コードからでもAPI仕様書の自動生成ができるから

Spring, JAX-RS, Servletに対応
- swagger-coreのGitに明記されている
既存ソースにアノテーション貼って、ちょっと設定用コードかくだけで動く
- 途中からでも導入できる！（と期待している）
ボトムアップ形式というらしい

その３：デファクタスタンダードだから

まだなってない気がするけど、たぶんなる、たぶん…。
フォーマットについて、一度学習すれば他の現場他の案件でも同じ
そのフォーマットを見慣れることになるので、見落としが減る

今回はボトムアップ形式について見てみましょう

サンプルアプリを作ってみた
- 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

変更点

f:id:kogayushi:20180413233949p:plain

Swagger UI

f:id:kogayushi:20180413234008p:plain

ダメなところ

リクエストパラメーターがわかりにくい
レスポンスパラメーターがわかりにくい
formパラメーターでは具体的に何を送るべきかわからない 4.サンプル値がない 5.model見ると全部optionalってありえない 6.定義してない4XX Http Statusがならんでる
401/403は使ってない
5XX Http Statusがない
- ありえない
少なくとも予期せぬエラーで500は絶対に返すことある