Compiler APIを利用してAPI型定義ファイルからOpenAPI.jsonを作成する

2024年5月8日（水）に開催された「TypeScript Developers Meetup 〜フロントからバックまでTypeScript〜」にコミューン株式会社 ソフトウェアエンジニアの角田 武蔵さんが登壇した際の資料です。ぜひ、ご覧ください。

リンク集
・コミューン株式会社コーポレートサイト：https://communeinc.com/ja
・採用情報：https://communeinc.com/ja/careers
・会社情報　エンジニアVer：https://www.notion.so/commmune/ver0b895a0187ef4954a2d5182afd82082d
・Commune Engineer Blog：https://tech.commune.co.jp/
・Xアカウント（Commune Developers）：https://twitter.com/CommuneDev

Transcript

1. Compiler APIΛར༻ͯ͠ APIܕఆٛϑΝΠϧ͔Β
 OpenAPI.jsonΛ࡞੒͢Δ TypeScript Developers Meetup 
 ʙϑϩϯτ͔ΒόοΫ·Ͱ TSʙ 2024/05/08
2. AGENDA 1. ࣗݾ঺հ 2. Communeͷٕज़ελοΫ 3. Communeʹ͓͚ΔAPIͷܕఆٛ 4. ࠷ۙͷ՝୊ 5. APIܕఆٛϑΝΠϧ͔ΒOpenAPI.jsonΛ࡞੒ 6. ࠓޙͷ՝୊ 7. ·ͱΊ
3. © Commune Inc. All rights reserved ֯ా෢ଂ (a.k.a. Buzo) Tech & Platform Software engineer Musashi Tsunoda ڈ೥ͷ8݄ʹίϛϡʔϯגࣜձࣾʹೖࣾɻ TypeScriptʹΑΔόοΫΤϯυɾϑϩϯτΤϯυ྆ ํͷ։ൃΛߦ͏ɻ ུ֓ SNS X: @buzou_muzou ࣗݾ঺հ ޷͖ͳ͜ͱ ݸਓ։ൃͱϘΫγϯά
4. Communeͷٕज़ελοΫ
5. © Commune Inc. All rights reserved Communeͷٕज़ελοΫ όοΫΤϯυ ϞόΠϧΞϓϦ ϑϩϯτΤϯυ
6. © Commune Inc. All rights reserved • Web͸TypeScriptͰ౷Ұ ◦ ֶशίετ͕௿͍ ◦ ࠾༻ͷ໘ͰͷΤϯδχΞͷ֬อͷ༏Ґੑ ◦ ܕఆٛϑΝΠϧͷڞ༗ʹΑΔ։ൃͷޮ཰Խ • ϞόΠϧ͸Flutter ◦ ΫϩεϓϥοτϑΥʔϜͳ։ൃ Communeͷٕज़ελοΫ
7. Communeʹ͓͚Δ APIͷܕఆٛ
8. © Commune Inc. All rights reserved όοΫΤϯυɾϑϩϯτΤϯυͰAPIͷܕఆٛͷڞ༗ Communeʹ͓͚ΔAPIͷܕఆٛ
9. ࠷ۙͷ՝୊
10. © Commune Inc. All rights reserved • APIͷฦ٫஋ͷϥϯλΠϜͰͷܕͷෆҰக ◦ booleanͷ͸͕ͣ 0 or 1ʹͳ͍ͬͯΔ ◦ numberͷ͸͕ͣstringʹͳ͍ͬͯΔ ◦ etc • ϞόΠϧνʔϜͱͷ࿈ܞ ◦ APIΤϯυϙΠϯτͷ
 ৽ن࡞੒ɾ࢓༷มߋ࣌ͷೝࣝͣΕ ࠷ۙͷ՝୊
11. OpenAPI.jsonΛ࡞Ζ͏
12. © Commune Inc. All rights reserved • Compiler APIͰAPIܕఆ͔ٛΒOpenAPI.jsonΛ࡞੒͢Δ ◦ εΩʔϚۦಈͷAPI։ൃʹγϑτ ◦ ϞόΠϧνʔϜͱͷ࿈ܞʹ࢖༻ • OpenAPI.jsonΛݩʹೖग़ྗͷܕνΣοΫΛಋೖ ◦ ϥϯλΠϜͷϦΫΤετͱϨεϙϯεͷܕΛอূ ํ਑
13. Compiler APIͱ͸
14. © Commune Inc. All rights reserved Compilier APIͱ͸ • TypeScriptͷτϥϯεύΠϧ࣌ʹߦ͍ͬͯΔΑ͏ͳॲཧΛ
 ݺͼग़͢͜ͱ͕Ͱ͖ΔAPI • ίʔυΛந৅ߏจ໦(AST)ͱͯ͠ղੳ͕Ͱ͖Δ • ίʔυͷม׵΍ࣗಈੜ੒ͳͲʹར༻͢Δ͜ͱ͕Ͱ͖Δ • Web APIͰ͸ͳ͍ • TypeScriptͷ։ൃݩ͕ެ։͍ͯ͠Δ
 https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API
15. Compiler APIΛ࢖ͬͯ OpenAPI.jsonΛ࡞੒͢Δ
16. © Commune Inc. All rights reserved ΰʔϧ: APIܕఆٛϑΝΠϧ͔ΒOpenAPI.jsonΛ࡞੒ OpenAPI.jsonΛ࡞੒
17. © Commune Inc. All rights reserved OpenAPI.jsonΛ࡞੒ Tsunagger *ʮͭͳ͙ + Swaggerʯ͔Β໋໊ *Tsunoda(ࢲͷ໊લ)ͱ͸Ұ੾ؔ܎ͳ͍ OpenAPI.json͕ੜ੒Ͱ͖ΔεΫϦϓτΛ࡞੒ npm run tsunagger Ͱ
18. © Commune Inc. All rights reserved OpenAPI.jsonΛ࡞੒ CommuneͷAPIܕఆٛϑΝΠϧ • Type͕HTTPϝιου໊ ◦ ΤϯυϙΠϯτύε໊ ▪ ϦΫΤετͷܕఆٛ ▪ Ϩεϙϯεͷܕఆٛ
19. © Commune Inc. All rights reserved OpenAPI.jsonΛ࡞੒ • ΤϯυϙΠϯτͷύε໊͝ͱ ◦ HTTPϝιου໊ ▪ ϦΫΤετͷܕఆٛ ▪ Ϩεϙϯεͷܕఆٛ OpenAPIʹΑΔAPIεΩʔϚఆٛ
20. © Commune Inc. All rights reserved OpenAPI.jsonΛ࡞੒ foo: string “foo”: {“type”:”string”}, bar: number “bar”: {“type”:“number”} baz: { foo: string, bar: number } “baz”: { “type”: “object”, "properties": { “foo”: {“type”:”string”}, “bar”: {“type”:“number”} } } TypeScript OpenAPI.json
21. © Commune Inc. All rights reserved OpenAPI.jsonΛ࡞੒ Compiler APIΛۦ࢖ͯ͠ɺ
 TSͷந৅ߏจ໦͔ΒܕఆٛΛղੳ͍ͯ͘͠
22. © Commune Inc. All rights reserved OpenAPI.jsonΛ࡞੒ https://ts-ast-viewer.com/
23. © Commune Inc. All rights reserved 1. TSϑΝΠϧͷಡΈࠐΈ 2. ts.SourceFileϑΝΠϧΦϒδΣΫτͷੜ੒ 3. ֤ϊʔυͰܕͷγϯϘϧΛऔಘ a. Object΍Arrayܕͷ৔߹͸
 ͞ΒʹͦͷࢠϊʔυͷܕͷγϯϘϧΛऔಘ 4. OpenAPI.jsonͷܗࣜʹͯ͠ϑΝΠϧʹग़ྗ OpenAPI.jsonΛ࡞੒ TsunaggerͷॲཧͷྲྀΕ
24. © Commune Inc. All rights reserved OpenAPI.jsonΛ࡞੒ OpenAPI.jsonͷ࡞੒ͷࣗಈԽʹ੒ޭ! ͦΕʹΑΓҎԼ͕࣮ݱͨ͠ • Swagger UIͰOpenAPI.jsonΛݩʹAPI࢓༷ॻͷڞ༗ • openapi-request-validatorΛ༻͍ͨ
 APIͷres/reqόϦσʔγϣϯ
25. © Commune Inc. All rights reserved ม׵ॲཧͰ٧·ͬͨՕॴ • Class • ϢχΦϯܕ • ॥؀ࢀরʹͳ͍ͬͯΔܕ • τϦοΩʔͳܕఆٛ ݸผʹରԠ͸Մೳ͕ͩɺͦͷ෼ίʔυ͸ෳࡶʹͳ͍ͬͯ͘ɻɻɻ APIͷreq/resͷఆٛఆ͕ٛҎԼͷΑ͏ͳ৔߹
26. ࠓޙͷ՝୊
27. © Commune Inc. All rights reserved ࠓޙͷ՝୊ • Tsunaggerͷอक • ୯७ͳΦϒδΣΫτ΍
 ϓϦϛςΟϒͳܕఆٛͰ͸ͳ͍৔߹ͷରॲ • ผͷํ๏ͷݕ౼ ◦ APIܕఆٛΛzodͰߦ͍ɺzod-to-openapi౳
 ֎෦ϥΠϒϥϦͰOpenAPI.jsonΛ࡞੒ ◦ zod΁ͷҠߦظؒத͸TsunaggerʹΑΔOpenAPI.jsonΛ
 ར༻͢Δ༧ఆ
28. ·ͱΊ
29. © Commune Inc. All rights reserved • ϑϩϯτΤϯυͱόοΫΤϯυͰ͸
 APIͷܕఆٛϑΝΠϧΛڞ༗͍ͯ͠Δ ·ͱΊ • ϞόΠϧͱͷ࿈ܞͷͨΊʹOpenAPI.json͕ඞཁʹͳͬͨ • Compiler APIΛར༻͠ɺ
 TSͷܕఆٛϑΝΠϧ͔ΒOpenAPI.json͕࡞੒Ͱ͖ͨ • ୯७Ͱͳ͍ܕఆٛͷม׵͸ՄೳͰ͋Δ͕ίʔυ͕ෳࡶʹͳΔ
30. ࠷ޙʹએ఻Ͱ͢📢
31. © Commune Inc. All rights reserved 31 ίϛϡʔϯ͸͋ͳͨͷΩϟϦΞΛ࣮ݱ͢ΔϏʔΫϧͰ͢ʂ XΞΧ΢ϯτ @CommuneDev ϑΥϩʔ͓ئ͍͠·͢! ΤϯδχΞ޲͚ձࣾ৘ใ https://commmune.notion.site/ver- 0b895a0187ef4954a2d5182afd82082d
32. 32 © Commune Inc. All rights reserved