Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
「つなぎこみ」を自動化する
Search
Nkowne63
March 28, 2019
Technology
0
480
「つなぎこみ」を自動化する
swagger-jsによる「APIドキュメントからのAPIクライアントの自動生成」によって、バックエンドとスムーズに連携する。
Nkowne63
March 28, 2019
Tweet
Share
More Decks by Nkowne63
See All by Nkowne63
TypeScriptのコード生成をつらくしないために
neutron63zf
1
710
2020-11-05-side-effects-composition__1_.pdf
neutron63zf
1
440
vueで中規模以上のフロントエンドを組んでいて 役に立ったtips
neutron63zf
5
3.2k
20200128_nkowne63
neutron63zf
0
36
Vueで「見た目」「振る舞い」を分離してみよう
neutron63zf
0
590
20190523_nkowne63zf_1.pdf
neutron63zf
0
400
for文禁止縛り in JS
neutron63zf
0
730
Other Decks in Technology
See All in Technology
BigQuery Remote FunctionでLooker Studioをインタラクティブ化
cuebic9bic
3
300
Github Copilot エージェントモードで試してみた
ochtum
0
110
TechLION vol.41~MySQLユーザ会のほうから来ました / techlion41_mysql
sakaik
0
180
Amazon ECS & AWS Fargate 運用アーキテクチャ2025 / Amazon ECS and AWS Fargate Ops Architecture 2025
iselegant
16
5.6k
How Community Opened Global Doors
hiroramos4
PRO
1
120
25分で解説する「最小権限の原則」を実現するための AWS「ポリシー」大全 / 20250625-aws-summit-aws-policy
opelab
9
1.1k
製造業からパッケージ製品まで、あらゆる領域をカバー!生成AIを利用したテストシナリオ生成 / 20250627 Suguru Ishii
shift_evolve
PRO
1
140
生成AI時代の開発組織・技術・プロセス 〜 ログラスの挑戦と考察 〜
itohiro73
0
200
なぜ私はいま、ここにいるのか? #もがく中堅デザイナー #プロダクトデザイナー
bengo4com
0
460
Observability в PHP без боли. Олег Мифле, тимлид Altenar
lamodatech
0
350
より良いプロダクトの開発を目指して - 情報を中心としたプロダクト開発 #phpcon #phpcon2025
bengo4com
1
3.1k
Абьюзим random_bytes(). Фёдор Кулаков, разработчик Lamoda Tech
lamodatech
0
340
Featured
See All Featured
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
124
52k
Statistics for Hackers
jakevdp
799
220k
RailsConf 2023
tenderlove
30
1.1k
Performance Is Good for Brains [We Love Speed 2024]
tammyeverts
10
930
Product Roadmaps are Hard
iamctodd
PRO
54
11k
BBQ
matthewcrist
89
9.7k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
194
16k
Intergalactic Javascript Robots from Outer Space
tanoku
271
27k
Building a Modern Day E-commerce SEO Strategy
aleyda
42
7.3k
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
331
22k
Designing Experiences People Love
moore
142
24k
ReactJS: Keep Simple. Everything can be a component!
pedronauck
667
120k
Transcript
「つなぎこみ」を自動化する swagger-jsによるフロントエンドとバックエンドの連携
自己紹介 張 たいよ (GitHub: @neutron63zf) 東京大学理学部物理学科 新4年 • ventus-inc ◦
JavaScript ( Vue.js / Nuxt.js ) ◦ Golang / Firebase • 東京大学五月祭常任委員会 ◦ AWS / Nginx / Docker ◦ Node.js ( Express )
構成 • 背景 • swagger-jsの概要 • 実際につないでみる • メリット、デメリット •
まとめ
背景 「つなぎこみ」はめんどくさい • 「つなぎこみ」とは • シンプルな「つなぎこみ」 • 問題点1:コピペコードの量産 • 問題点2:仕様の追跡
• まとめ
「つなぎこみ」とは 右側の様に、バックエンド APIに対してフロント エンドからリクエストを送ってデータを受け取る 処理を書くこと。 フロントエンドとバックエンドが分離したシステ ムだとほぼ必須。 XHR, $.ajax, superagent,
axios, fetchなどい ろいろクライアントがある。 出典:https://jp.vuejs.org/v2/cookbook/using-axios-to-consume-apis.html
シンプルな「つなぎこみ」 前のスライドのようにviewに近い部分に書い てしまうこともあるが、素のライブラリをラップし て、関数として切り出しておくと複数の場所で 使う場合などで取り回しやすかったりする。 レスポンス形式はともかく、リクエスト形式に関 する知識が必要。
問題点1:コピペコードの量産 エンドポイントの数だけ上のようなコードを書 かないといけない。 10-20個程度なら楽だが、ventusのwhooop! のようなサービスだとエンドポイントの数は 100個レベルになるため少ししんどい。 APIドキュメントを機械的に翻訳する人になっ てしまう。 (社内サービスとして作ったコードのリクエスト関数たち)
問題点2:仕様の追跡 (ある程度は仕方ないことだが) APIのリクエス ト形式が変わると関数も書き換えないといけな い。 そして結構変更忘れが起きる。 APIドキュメントと実装が違っていてバグること がある。 (リクエスト形式に伴う変更の例)
まとめ • APIにリクエストを飛ばすのはほとんど避けて通れない • でも、複雑なアプリケーションだとエンドポイントごとに関数を用意するのは結構めんどくさい • しかも、APIの仕様を追跡してそれらを保守しないといけない →APIドキュメントがあっても、それをうまく活用できてない。 →APIドキュメントから自動で関数(APIクライアント)を生成できれば楽なんだけ どなあ...
swagger-jsの概要 swagger-jsとswagger-codegenの紹 介 • swagger-jsについて • swagger-codegenについて(おまけ)
swagger-jsについて APIドキュメンテーションツールとして有名な swaggerだが、結構いろいろな周辺ツールが ある。 その中の一つであるswagger-jsを使うと、 swaggerの形式に従ったAPIドキュメントから APIクライアントを自動で作ってくれる。 (GitHubのページ。 リポジトリ名はswagger-jsだが、名前はswagger client)
swagger-codegen について(おまけ) 他の言語やFW、たとえばTypeScriptやRails, Javaなどで同じことをしようとするとこれを使う ことになる。 また、swaggerのドキュメントから簡易的なスタ ブサーバーを立てることもできる。 ただし細かいカスタマイズには Javaが必要な ため少々書きづらい。自前でパーサーを書くと
いう手もある。 (GitHubのページ。 使用可能な言語のリストがずらっと並ぶ。)
実際につないでみる 具体的な実装 • インストール • swaggerドキュメントを読み込む • リクエストを飛ばす ◦ operationIdを知る
◦ パラメーターを指定する ◦ 実際にやってみる • カスタマイズする • その他
インストール npm, yarnでインストール可能 CDNでも使える (GitHubより)
swaggerドキュメントを 読み込む(1) 一番基本的な使い方は、「 swaggerで書かれ たAPIドキュメントをネット越しに読み込む」と いうもの。 APIドキュメントはjsonを返すエンドポイントで なくてはいけない。 APIクライアントはPromiseとして返ってくるの で、awaitすると便利。
swaggerドキュメントを 読み込む(2) 公式docsには書かれていないので少しトリッ キーだが、直接jsonをパースしたオブジェクト を渡して初期化することもできる。 ローカルでswaggerのファイルを管理したいと きなどは便利。
リクエストを飛ばす 一旦読み込んでしまえばあとは簡単なのだが、リクエストに必要な情報を 2つ知る必要がある。 • どのエンドポイントに、何のメソッドを使って飛ばすか( operationId) • パラメーターは何か この2つを順番に解説していく。
operationIdを知る 「どのエンドポイントに、何のメソッドを使って飛 ばすか」をoperationIdとして把握する。(少し めんどい) swaggerのjsonに書かれている場合もある が、何も書かれていない場合は、「 post_pet」 のように、「${method}_${path}」のような名前 が自動で割り振られる。 pathのうち半角英数字でないものは全て「
_」 に置き換えられる。 (swagger petstoreでの例)
パラメーターを指定する POSTやGETなどのクエリパラメーターなどを swaggerをもとに調べる。 そのパラメーターがqueryなのか、path parameterなのか、bodyなのかなどは swaggerが自動で判別して入れてくれる(地味 に助かる。) (swagger petstoreの例)
実際にやってみる 実際に2つを指定してリクエストを飛ばすスクリ プトは右のようになる。 baseUrlなどは全てswaggerに記述されてい いるものがデフォルトで使用される。 (swagger petstoreの例)
カスタマイズする 例えば、swaggerにbaseUrlが無かったり、リ クエストヘッダをいじりたい(例 :multipart/form-dataにしたい)ときなどは、 リクエストを組み立てていじることが可能。 (リクエストをいじることも可能)
カスタマイズする 例えば、swaggerにbaseUrlが無かったり、リ クエストヘッダをいじりたい(例 :multipart/form-dataにしたい)ときなどは、 リクエストを組み立てていじることが可能。 リクエストを組み立てるだけの 「buildRequest」メソッドと、送信するだけの 「http」メソッドがある。(いずれも staticメソッ ド)
(リクエストをいじってから送信する)
その他 実際に使うときは、従来の「リクエストを送信する関 数を使う方式」も「operationIdとparameter」で送信 できるようにしておくと都合がいい。 (whooop!では、swagger-jsを拡張して、これらをプ ラグインできるようなクラスを使用している。) (再掲:従来の「リクエストを送信するだけの関数」)
メリット、デメリット 実際に開発で使ってみて思ったこと • メリット ◦ 実装コストの削減 ◦ APIリクエストのカプセル化 • デメリット
◦ swaggerに強く依存する ◦ カスタマイズが少しは必要
実装コストの削減 swaggerを更新するだけでリクエストを飛ばせ るようになったので、だいぶ快適になった。 また、パラメーターが足りないときはリクエスト を組み立てる段階でエラーが出るので bad requestが減る。 operationIdもまとめて書いておけば補完が 効くし、素の関数を書くより頭を使わなくてい い。
(補完のための一覧。なくてもリクエストは飛ばせる。)
APIリクエストのカプセル化 リクエストのオブジェクトを簡単に作れるように なったので、いろいろな書き方ができるように なった。 whooop!ではnuxtを使っているが、「リクエス トの送信はページで、必要な情報(リクエスト) は各コンポーネントで組み立てる」という実装 で、DRYかつ、テストがしやすいようにしてい る。 (実装の例。
送信はページで、 リクエストの詳細は各コンポーネントが担当する。)
swaggerに強く依存する swaggerを読み込むという性質上、実際にエ ンドポイントがあっても、swaggerがなかった り、間違っていると送信できなかったりする。
カスタマイズが 少しは必要 複数の環境で同じswaggerを使っている場 合、baseUrlが同じになってしまうため、多少 のカスタマイズは避けられない。 他にも、ヘッダーが切り替わらなかったりする ので、そこも少しは実装しないといけない。 (再掲:ヘッダーやbaseUrlをいじったりする必要がある。)
まとめ • APIへのリクエスト関数を書いて保守す るのはめんどくさい • swagger-jsを使うと、swaggerのAPIド キュメントからリクエストを(かなりの割合 で)自動で作れる •
APIリクエストがカプセル化されていろん な書き方ができるようになる