Swagger
何が嬉しい？
調べれば調べるほどいろいろ出てきて非常にめんどいんだがmrsekut.icon
どれを見れば体系的に学べるのかもよくわからない
いったん保留しようかな。↓がだるかった
関連するツールやlibraryが多すぎてどれを使えばいいのかわからない
swaggerの何が嬉しいのかそもそもよくわかっていない
yamlにしても、jsdocにしてもかくのがだるすぎる
型から生成しろ
used by見たけどよくわからんかった
何ができる？
Swagger Spec を書いておけば自動的にドキュメント生成
ドキュメントから実際のリクエストを投げられる
paramsとか設定したり
apiの検索ができる
etc
bottom upにやっていく方法と、top downにやっていく方法とある
Swagger Specを記述し、それの基づきAPI（モック）を生成する方法（トップダウン）
既存のAPIにアノテーションを記述しSwagger Specを生成する方法（ボトムアップ）
ドキュメントと実装は別々
個人開発でも有用？
ドキュメントの自動生成が嬉しいポイントなのか？よくわからん
mockを作れる？
何が嬉しい？
documentを作れるのはわかったが、documentが作れたら何が嬉しいの？
手で書くのと何が異なる？
コメントであっても仕様書書くのだるくない？
型から生成してくれよ..
↓この辺のツールは組み合わせて使うものなのか？
ツール
REST APIに対して Swagger の仕様に準じたドキュメント
Web上でプレビューをみながら編集できるEditor
指定の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-jsdoc
Swagger UIのドキュメントをExpressから配信できるようにする
JSDocからSwagger UIで使用可能なjsonを作成 openapiのymlからtypescriptの型定義を生成する
デファクトスタンダードらしい
似たようなlibraryが多すぎて辛い
全く見てないのでしらんけど
OpenAPIの定義からリクエスト、レスポンスの型定義を自動生成
TypeScript API generator via Swagger scheme
OpenAPIのspecから、tsの型を生成する