Swagger
OpenAPIを用いてRESTful APIを設計する際に使用するツールセット
Open API Initiativeが推進している
>#WIP
何が嬉しい？
調べれば調べるほどいろいろ出てきて非常にめんどいんだが
どれを見れば体系的に学べるのかもよくわからない
いったん保留しようかな。↓がだるかった
関連するツールやlibraryが多すぎてどれを使えばいいのかわからない
swaggerの何が嬉しいのかそもそもよくわかっていない
yamlにしても、jsdocにしてもかくのがだるすぎる
型から生成しろ
typera-openapiあったけど、使い方がわからん
used by見たけどよくわからんかった
何ができる？
Swagger Spec を書いておけば自動的にドキュメント生成
ドキュメントてなに #??
ドキュメントから実際のリクエストを投げられる
paramsとか設定したり
apiの検索ができる
etc
bottom upにやっていく方法と、top downにやっていく方法とある
Swagger Specを記述し、それの基づきAPI（モック）を生成する方法（トップダウン）
既存のAPIにアノテーションを記述しSwagger Specを生成する方法（ボトムアップ）
ドキュメントと実装は別々
個人開発でも有用？
ドキュメントの自動生成が嬉しいポイントなのか？よくわからん
mockを作れる？
何が嬉しい？
OpenAPIとの関係性がよくわからない
documentを作れるのはわかったが、documentが作れたら何が嬉しいの？
手で書くのと何が異なる？
コメントであっても仕様書書くのだるくない？
型から生成してくれよ..
↓この辺のツールは組み合わせて使うものなのか？
ツール
REST APIに対して Swagger の仕様に準じたドキュメント
Web上でプレビューをみながら編集できるEditor
Swagger Specの設計書を記載する
Swagger Specで記載された設計からドキュメントをHTML形式で自動生成する
指定のyaml, jsonファイルを元にAPIリファレンスをWeb上に表示する
Web上でAPIを実行できる
Swagger Spec で記載された設計からAPIのスタブを自動生成
VSCode拡張
前提として
APIのdocsを書くツールは色々ある
その内の一つにswaggerがある
OpenAPIは、それらのツールの書き方を統一するための仕様
これはSwaggerより後発であり、
Swaggerをベースに仕様を作るわ、という感じになったらしい
YAMLとかJSONとかソースコメントとかいろんな書き方ができる
ドキュメントにAPIを実行するためのフォームが付いてくる
いろんなツールがあって、導入が複雑
なぜOpenAPI Specificationで書くか ref
OAS3.0で記述すことにより、API仕様書はどの言語にも依存していない
API仕様書からさまざまな言語に出力するライブラリが存在する
品質を担保できる
実装速度を高めることができる
なぜ #??
$ npm i -D swagger-ui-express swagger-jsdoc @types/swagger-ui-express @types/swagger-jsdocSwagger UIのドキュメントをExpressから配信できるようにする
どういう意味 #??
JSDocからSwagger UIで使用可能なjsonを作成
コメント上のtypoは防げないのか #??
typera-openapiあるやん
openapiのymlからtypescriptの型定義を生成する
デファクトスタンダードらしい
似たようなlibraryが多すぎて辛い
swt2dtsと似たようなやつで、こちらのほうがいいらしい
全く見てないのでしらんけど
OpenAPIの定義からリクエスト、レスポンスの型定義を自動生成
TypeScript API generator via Swagger scheme
OpenAPIのspecから、tsの型を生成する