OpenAPI Generatorで始める堅実なAPI Client開発 / Solid API Client Development with OpenAPI Generator

Frontend Conference Fukuoka スピンオフ 〜福岡人大集合の会〜 (2020-09-30) で登壇した資料です。

OpenAPI 定義から API クライアントを生成し、フロントエンド開発を堅実に進める方法を紹介しています。

Transcript

1. OpenAPI Generatorで始める 堅実なAPI Client開発 Frontend Conference Fukuoka スピンオフ ～福岡人大集合の会～ 2020.09.30 清家史郎 1
2. 自己紹介：清家 史郎 - ID - - 清家 史郎 @seike460 GitHub：seike460 Twitter：@seike460 Work at - 株式会社 Fusic （フュージック） 技術開発本部/技術開発第一部門 - チームリーダー/エバンジェリスト/プリンシパルエンジニア - Skill - - PHP／Go／AWS Personal - PHPカンファレンス福岡2020 幻の実行委員長 - Serverless Days Fukuoka 2019 co-chair 46fm パーソナリティ 2
3. Agenda 1. わたしと福岡 2. アプリケーション構成 3. OpenAPI Specification駆動開発 4. OpenAPI Generator ✕ TypeScript 3
4. 1 わたしと福岡
5. わたしと福岡 「わたしとうどん」と言っても過言ではありません 1. 2. 3. 4. 5. 6. 7. 8. 肉肉うどん 大地のうどん 牧のうどん 因幡うどん 葉隠うどん 釜喜利うどん 資さんうどん ウエスト 僕を大きく育ててくれました（物理〇〇Kg） かろのうどんに行けてない私を許して欲しい…！ 福岡は本当にご飯が美味しくいいところです。 地元大分から籍を移して定住する事を決意 みなさま、うどん食べましょう 5
6. 2 アプリケーション構成
7. アプリケーション構成 BackendにGo API、FrontendにReactを採用した SPA(Single Page Application)構成 7
8. アプリケーション構成 BackendとFrontendのAPI連携が相当数あるので、 連携に対する細かい齟齬などを是正する仕組みを入れたい 8
9. 3 OpenAPI Specification駆 動開発
10. Swagger SwaggerはOpenAPI仕様、OpenAPI Specification（以降、OAS)と言われる、 REST APIを定義するための標準仕様に基づいた一連のオープンソースフレームワーク REST APIの設計、構築、文書化、および使用に役立つ機能を提供します。 • • • Swagger Editor ◦ OASを書くためのエディタ Swagger UI ◦ OASからドキュメントを生成するツール Swagger Codegen ◦ OASからコードを生成するツール もともとSwagger SpecificationだったものがOpenAPI Specificationに改名されたものの、実装の 方はもとのブランドを維持したまま残した(らしい) 参考文献：OpenAPIとSwaggerを雑に動かして学ぶAPIドキュメントツール入門 10
11. Swagger Editor 11
12. Swagger UI 12
13. Stoplight Studio 夢のようなツールでは無いですが、YAMLとにらめっこするよりは 快適にOpenAPI Specification記述が可能 13
14. Stoplight Studio 14
15. 4 OpenAPI Generator ✕ TypeScript
16. OpenAPI Generator OpenAPI Generator OpenAPI Specification形式で記述されたYAMLやJSONから コード生成してくれるツール $ openapi-generator generate -g typescript-axios -i doc/swagger/hoge.v1.yaml -o frontend/src/api [main] INFO o.o.codegen.DefaultGenerator - Generating with dryRun=false [main] INFO o.o.codegen.DefaultGenerator - OpenAPI Generator: typescript-axios (client) [main] INFO o.o.codegen.DefaultGenerator - Generator 'typescript-axios' is considered stable. [main] INFO o.o.c.l.AbstractTypeScriptClientCodegen - Hint: Environment variable 'TS_POST_PROCESS_FILE' (optional) not defined. E.g. to format the source code, please try 'export TS_POST_PROCESS_FILE="/usr/local/bin/prettier --write"' (Linux/Mac) [main] INFO o.o.c.l.AbstractTypeScriptClientCodegen - Note: To enable file post-processing, 'enablePostProcessFile' must be set to `true` (--enable-post-process-file for CLI). [main] INFO o.o.codegen.AbstractGenerator - writing file /Users/seike460/src/github.com/fusic/hoge/frontend/src/api/index.ts [main] INFO o.o.codegen.AbstractGenerator - writing file /Users/seike460/src/github.com/fusic/hoge/frontend/src/api/base.ts [main] INFO o.o.codegen.AbstractGenerator - writing file /Users/seike460/src/github.com/fusic/hoge/frontend/src/api/api.ts [main] INFO o.o.codegen.AbstractGenerator - writing file /Users/seike460/src/github.com/fusic/hoge/frontend/src/api/configuration.ts [main] INFO o.o.codegen.AbstractGenerator - writing file /Users/seike460/src/github.com/fusic/hoge/frontend/src/api/git_push.sh [main] INFO o.o.codegen.AbstractGenerator - writing file /Users/seike460/src/github.com/fusic/hoge/frontend/src/api/.gitignore [main] INFO o.o.codegen.AbstractGenerator - writing file /Users/seike460/src/github.com/fusic/hoge/frontend/src/api/.npmignore [main] INFO o.o.codegen.AbstractGenerator - writing file /Users/seike460/src/github.com/fusic/hoge/frontend/src/api/.openapi-generator/VERSION 16
17. OpenAPI Generator ✕ TypeScript OpenAPI Generator ✕ TypeScriptでカッチリ型定義を行いながら開発することで 定まったコードを生成し、細かなミスを排除する →コードの質とスピードを加速させる →ビジネスロジックに集中する import { DefaultApi, Tag } from "../api/api"; ~ 省略 ~ const api = new DefaultApi(); ~ 省略 ~ const searchTags = (keyword: string) => { api .getTags(keyword) .then((res) => { setTags(res.data); }) .catch((err) => { alert(err.message); // エラー処理が甘いことはこの場では目をつぶってください }); }; 17
18. まだ出来る事がある 定義があればコード生成はフロントエンドだけでなく、バックエンドも出来る 18
19. Go ✕ OpenAPI Specification Go ✕ OpenAPI Specificationにて型定義されたコードの自動生成 $ swagger generate server -f doc/swagger/hoge.v1.yaml -t hoge/ 2020/09/30 06:53:25 validating spec /Users/seike460/src/github.com/fusic/hoge/doc/swagger/hoge.v1.yaml 2020/09/30 06:53:25 preprocessing spec with option: minimal flattening 2020/09/30 06:53:25 building a plan for generation 2020/09/30 06:53:25 generation target hoge/ 2020/09/30 06:53:25 planning definitions 2020/09/30 06:53:25 planning operations 2020/09/30 06:53:25 grouping operations into packages 2020/09/30 06:53:25 planning meta data and facades ~ 省略 ~ 2020/09/30 06:53:26 package field operations 2020/09/30 06:53:26 creating generated file "doc.go" in "hoge/restapi" as doc 2020/09/30 06:53:26 executed template asset:serverDoc 2020/09/30 06:53:26 Generation completed! For this generation to compile you need to have some packages in your GOPATH: * github.com/go-openapi/runtime * github.com/jessevdk/go-flags You can get these now with: go get -u -f hoge/... 19
20. Go Conference’20 in Autumn SENDAI Go APIを生成するSwagger駆動開発 on AWS Fargate バックエンド寄りのお話になりますが、興味あればぜひ（福岡から単身にビビってる） ▪connpass https://sendaigo.connpass.com/event/185474/ 20
21. まとめ Point 1 福岡はうどんがおいしい Point 2 SPAを作る上でのBackendとの連携をOpenAPI Specificationで決めて開発を進める Point 3 TypeScriptのコード生成、Goと合わせてガッチリ型制御を行いビジネスロジックに集中する Point 4 福岡はうどんがおいしい 21
22. Thank You ご清聴いただきありがとうございました We are Hiring ! https://recruit.fusic.co.jp/