まだAPI定義管理で消耗してるの？〜Swaggerを用いた大規模アプリ時代のAPI定義管理とコードジェネレート〜

まだAPI定義管理で消耗してるの？〜Swaggerを用いた大規模アプリ時代のAPI定義管理とコードジェネレート〜
for DroidKaigi 2018

Transcript

1. ·ͩAPIఆٛ؅ཧͰফ໣ͯ͠Δͷʁ SwaggerΛ༻͍ͨ େن໛ΞϓϦ࣌୅ͷ APIఆٛ؅ཧͱίʔυδΣωϨʔτ 2018/2/8
 #DroidKaigi
2. ౻ాୖຏ Twitter: @magie_pooh GitHub: @magiepooh גࣜձࣾFOLIO झຯɾಛٕ:
 ΫϥϑτϏʔϧɾ೔ຊञɾϚδοΫɾ࠵຾ ࣗݾ঺հ
3. ˞ਤද΍σʔλ౳͸͋͘·Ͱ΋αϯϓϧͰ͋Γɺকདྷͷӡ༻੒Ռ౳Λࣔࠦ͋Δ͍͸อূ͢Δ΋ͷͰ͸͋Γ·ͤΜɻ
4. എܠ - ΞϓϦͰ࣮ݱ͍ͨ͜͠ͱ͕ෳࡶɾଟ༷Խ - αʔόʔͱΞϓϦΛ։ൃ͢ΔΤϯδχΞ͕ ผΕ͍ͯΔ͜ͱ͕ଟ͍ - ͦͷதͰɺεϐʔυΛอͬͨ։ൃ
5. ίϛϡχέʔγϣϯΛԁ׈ʹ ϛεΛىͣ͜͞ ਝ଎ʹ৘ใڞ༗
6. ҉໧஌ͷܗࣜԽ - ҉໧஌ͷॻ͖ग़͠ - ࣄྫͷڞ༗
7. ҉໧஌ͷܗࣜԽ - ҉໧஌ͷॻ͖ग़͠ → υΩϡϝϯτԽ - ࣄྫͷڞ༗ → αϯϓϧσʔλ
8. Έͳ͞Μɺ APIఆٛ؅ཧͯ͠·͔͢ʁ
9. APIఆٛͷϝϦοτ - ೝࣝͷᴥᴪΛͳ͘͢ - ৄࡉʹఆٛ͞Ε͍ͯΔͱɺؒҧ͍͕ى͖ʹ͍͘ - ख໭ΓΛͳ͘͢ ʢ˞ ϝϯς͠ଓ͚Δʣ
10. APIఆٛΛ؅ཧ͠Α͏
11. Ͳ͏΍ͬͯఆٛ͢Δʁ - Swagger - Protocol Buffers - api blueprint - Excel - ͦͷଞ
12. Ͳ͏΍ͬͯఆٛ͢Δʁ - Swagger - Protocol Buffers - api blueprint - Excel - ͦͷଞ
13. SwaggerΛ༻͍ͨ APIఆٛ
14. - The world’s Most Popular Framework for APIs - ϚΠΫϩιϑτɺGoogleɺIBMɺIntuitɺ PayPalɺ3ScaleɺApigeeɺCapital Oneɺ RestletɺSmartBear্ཱ͕ͪ͛ͨOpenAPI Initiativ͕APIهड़ͷͨΊʹSwaggerΛ࠾༻ Swagger
15. - REST APIͷઃܭ͔ΒυΩϡϝϯτԽɺςετɺ σϓϩΠ·ͰΛΧόʔ - APIఆٛ - Blueprint(ϞοΫ) - Codegen Swagger
16. ͜͜ʹςΩετΛೖΕ·͢ɻ ͻͱͭͷεϥΠυʹ಺༰Λ٧Ί͗͢ͳ͍Α͏ʹ͠·͠ΐ͏ɻ Կ౓΋͏Δ͍͞Α͏Ͱ͕͢ʮ̍ຕͷεϥΠυʹ̍ͭͷҙຯʯ ͕εϥΠυ࡞ΓͷجຊͰ͢ɻ Swagger Tools Tool Description Swagger Core Java-related libraries for creating, consuming, and working with Swagger definitions Swagger Editor Browser based editor for authoring Swagger definitions using YAML Swagger UI An HTML5 based UI for exploring and interacting with a Swagger defined API Swagger Codegen A code generation framework for building Client SDKs, servers, and documentation from Swagger Definitions
17. Swagger Editor
18. APIఆٛΛϨϯμϦϯά͠ͳ͕Βɺฤू͢Δ͜ͱ͕Ͱ͖Δ OnlineEditor https://swagger.io/swagger-editor/ Swagger Editor
20. "1*ͷϕʔε63-
21. εΩʔϚ
22. "1*ͷύε
23. )551ϝιου
24. CPEZͷఆٛ 1FUΦϒδΣΫτ
25. Ϩεϙϯε
26. EFpOJUJPOT
28. ඞਢ ϓϩύςΟ
29. 4USJOHܕ
    FY
    EPHHJF
30. UZQFͱGPSNBUͰܕ͕ܾ·Δ ˠMPOHܕ
31. Swagger UI
33. APIΛఆٛͯ͠΋ɺ ࣮૷ΛϛεΔͱ͖͸ ϛεΔΑͶʁ
34. ίʔυ͸ ػցతʹੜ੒͠Α͏
35. Swagger Codegen
36. Swagger Codgenͱ͸ - SwaggerͰఆٛͨ͠ϑΝΠϧ͔Βɺίʔυ΍ υΩϡϝϯτΛࣗಈੜ੒ - ΫϥΠϯτ - Model - Api - Docs
37. ActionScript, Ada, Apex, Bash, C# (.net 2.0, 3.5 or later), C++ (cpprest, Qt5, Tizen), Go, Groovy, Haskell (http-client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Rest-assured), Kotlin, Lua, Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-C, Scala (akka, http4s, swagger-async-httpclient), Swift (2.x, 3.x, 4.x), Typescript (Angular2.x, Fetch, Node) Supported Languages
38. ػցతʹੜ੒͢Δ͜ͱʹΑͬͯ - ޻਺࡟ݮ - JSONͷϚοϐϯάΦϒδΣΫτΛखॻ͖͢ Δͷ͸ਏ͍ - ਓҝతϛεͷհೖΛڐ͞ͳ͍ - ςετ͢΂͖ର৅͕ݮΔ - υΩϡϝϯτ࡞੒ऀͷҙਤ௨Γͷ࣮૷ʹͳΔ - ҙਤͷဃ཭Λͳ͘͢
39. swagger-codegen-cli generate \ -i swagger.yaml \ -l kotlin -i : input file -l : language ੜ੒ํ๏
40. Model
41. API(Kotlin) ,PUMJO͸ಠࣗͷ࣮૷ʹͳ͍ͬͯΔ
42. API(Java:Retrofit+Rx) +BWB͸3Y+BWB
    3FUSPpU͕αϙʔτ͞Ε͍ͯΔ
    ˠ
    "1*ʹؔͯ͠͸,PUMJO͸࢖͍ʹ͍͘ɾɾ
43. Docs(API)
44. Docs(Model)
45. Swagger CodegenͰ ϞοΫαʔό΋࡞ΕΔ
46. Swagger Editor͔Β
47. ϞοΫαʔόΛίϚϯυ͔Β࡞੒ swagger-codegen generate \ -i petstore.yaml -l nodejs-server ͜ΕͰNode.jsͷίʔυ͕ੜ੒͞ΕΔͷͰɺ͋ ͱ͸্ཱͪ͛Δ͚ͩ
48. ϞοΫαʔόͷϝϦοτ - ΞϓϦͰ࢖༻͍ͯ͠ΔAPIఆٛͷόʔδϣϯͱ ϞοΫαʔόͷόʔδϣϯΛ߹Θ͓ͤͯ͘ͱɺ αʔόଆͷ։ൃ଎౓ʹؔ܎ͳ͘ΞϓϦ։ൃऀ ͷ։ൃεϐʔυͰରԠՄೳ - ৗʹ৽͍͠ϞοΫαʔόΛ࢖͏ඞཁ͸ͳ͍ - ΞϓϦͰఆٛΛ൓өͨ͠Βɺ্ཱͪ͛ΔϞο ΫαʔόΛม͑Ε͹ྑ͍ - αʔόʔΤϯδχΞʹ଴ͬͯ΋Β͏ඞཁͳ͠
49. ϞοΫαʔόͷσϝϦοτ - ϦετͷΞΠςϜ਺͸ৗʹ̍ͭ
50. ࣮ࡍͷӡ༻
51. Q.FOLIOͰͲ͏΍ͬͯ ӡ༻͍ͯ͠Δͷʁ
52. FOLIO͸ϚΠΫϩαʔϏεΞʔΩςΫνϟ #'' .JDSPTFSWJDF .JDSPTFSWJDF .JDSPTFSWJDF .JDSPTFSWJDF "OESPJE J04 #''͸.JDSP4FSWJDF܊ͱ
    ಠཱͯ͠ϑϩϯτدΓɻ
    #''Λ։ൃ͢Δਓͱ
    ΞϓϦΤϯδχΞͷίϛϡχέʔγϣϯɻ
53. ӡ༻ํ๏ #'' #''୲౰͕σβΠϯΛݟͯɺ"1*ఆٛΛ࡞ͬͯ13 "1*ఆٛ͜ΜͳͷͲ͏ʁ 13 "OESPJE J04
54. ӡ༻ํ๏ #'' ΞϓϦଆ΋ؚΊͯϨϏϡʔ "1*ఆٛ͜ΜͳͷͲ͏ʁ Αͦ͞͏ʂ
 ͜ͷΦϒδΣΫτɺ
    ଞͷ"1*ͱڞ௨ԽͰ͖Δ͔΋ʁ 13 3FWJFX "OESPJE J04
55. ӡ༻ํ๏ #'' ໰୊΍վળ͕͋Ε͹ɺ
    ΞϓϦଆ͔Β*TTVF΍13Ͱٞ࿦ ͜Μͳײ͡ʹ͍ͨ͠ʂ *TTVF13 "OESPJE J04
56. ӡ༻ํ๏ #'' ໰୊΍վળ͕͋Ε͹ɺ
    ΞϓϦଆ͔Β*TTVF΍13Ͱٞ࿦ -(5. ͜Μͳײ͡ʹ͍ͨ͠ʂ *TTVF13 3FWJFX "OESPJE J04
57. ӡ༻ํ๏ - masterʹϚʔδޙɺλάΛ੾Δ - ֘౰ͷλάΛsubmoduleͱͯ͠ࢀর͢Δ - ʢຊ౰͸͍Ζ͍Ζ͍͕ͨ͠ɺ࡯͍ͯͩ͘͠͞ʣ - BFF͸ϑϩϯτʹґଘͯ͠Α͍ͷͰɺΞϓϦଆͷ ࢖͍΍͍͢Α͏ʹఆٛ͠ɺGitHub্Ͱٞ࿦͢Δ
58. Q.1ͭͷYAMLϑΝΠϧͰ؅ཧ ͢Δͷ͸ਏ͘ͳ͍ʁ
59. ͭΒ͍
60. ̍ͭͷyamlϑΝΠϧʹ͢΂ͯఆٛ͢Δͷ͸ਏ͍ͷ Ͱɺฤू࣌͸ϑΝΠϧ෼ׂͯ͠ఆٛ͠ɺϏϧυ࣌ʹ ݁߹͢Δɻ → multi-file-swaggerΛ༻͍Δ ࣮ࡍʹఆٛ͢Δํ๏
61. multi-file-swagger
62. multi-file-swagger
63. $npm install multi-file-swagger $multi-file-swagger \ -o yaml index.yaml >compiled.yaml https://www.npmjs.com/package/multi-file-swagger multi-file-swagger
64. Q. APIఆٛͷ όϦσʔτ͸Ͳ͏ͯ͠Δʁ
65. $npm install swagger-cli $swagger validate compiled.yml https://www.npmjs.com/package/swagger-cli pre-commitͰcompileͱvalidate͕૸ΔΑ͏ʹ͠ ͓ͯ͘ swagger-cli
66. Q. gRPC+Protocol BuffersΛ ࢖͍ͬͯΔ͔Βɺ Swagger͸ඞཁͳ͍ʁ
67. .protoϑΝΠϧ͔Β.javaϑΝΠϧΛੜ੒Մೳͳͷ ͰɺCodegen͸ඞཁͳ͍ɻ ͕ɺSwagger༻ͷJSONఆٛ΋ు͖ग़ͤΔͷͰɺ SwaggerUIͰυΩϡϝϯτͷڞ༗͸Մೳɻ →Swagger͸࢖͑ΔൣғͰ࢖͑͹ྑ͍ Codegen͸ඞཁͳ͍͕ɺSwaggerUI͸࢖͑Δ
68. Q. ͳͥFOLIO͸ gRPC + ProtocolBuffersΛ ࢖Θͳ͔ͬͨͷʁ
70. ཧ༝͸લํ/ޙํޓ׵ੑΛอͭͨΊɻ proto3Ͱrequired͕ͳ͘ͳͬͨ message SearchRequest { required string query = 1; optional int32 page_number = 2; optional int32 result_per_page = 3; } syntax = "proto3"; message SearchRequest { string query = 1; int32 page_number = 2; int32 result_per_page = 3; }
71. - BFFͱ͍͏ଘࡏ͕͋ΔͨΊɺ͕ͬͪΓܕ͕͋Δํ ͕ϝϦοτେ͖͔ͬͨ - APIఆٛͷޙํޓ׵ੑ͸ͳͯ͘΋Α͍ - swaggerͷbasePathΛv1, v2ͷΑ͏ʹରԠ →ࠓճ͸࢖Θͳͯ͘΋Α͍͔ͳɾɾ ʢݸਓతʹ͸࢖͍͍ͨʣ proto3Λ࢖Θͳ͔ͬͨཧ༝
72. ಋೖͯ͠Α͔ͬͨ͜ͱ͸ʁ
73. ಋೖͷར఺ - BFF؍఺ - Flowtypeͷܕ͕ੜ੒Ͱ͖ͯյΕʹ͍͘ - BFFͷઃܭͱflowtype / @KeitaMoromizato - https://qiita.com/KeitaMoromizato/items/d749d472f60ba4031b69 - iOS؍఺ - API, ModelΫϥε·Ͱࣗಈੜ੒ - KotlinΑΓ΋͞Βʹଟ͘ͷΫϥε͕ϓϩδΣΫτʹಋೖՄೳͳϨ ϕϧ - SwaggerͰ࢝ΊΔAPIఆٛ؅ཧͱίʔυδΣωϨʔτ/ਿ্ ༸ฏ - https://www.youtube.com/watch?v=agZ6T72lXzo
74. Q. ΧελϚΠζ ͍ͨ͠Μ͚ͩͲɺ Ͱ͖Δʁ
75. Ͱ͖·͢
76. - JavaͰॻ͔ΕͨXxxClientCodegen - ֤ݴޠͷܕΛܾΊΔ - ΦϓγϣϯͷॲཧͳͲͳͲ - mustacheه๏Ͱهड़͞ΕͨςϯϓϨʔτ - ClientCodegenͰ౉͞Εͨ஋ΛϚοϐϯά → ClientCodegen͔ɺςϯϓϨʔτʹखΛՃ͑Δ Swaggerͷߏ੒
77. mustacheه๏ͷجૅ mustache: Logic-less templates Hello {{name}} You have just won {{value}} dollars! {{#in_ca}} Well, {{taxed_value}} dollars, after taxes. {{/in_ca}} { "name": "Chris", "value": 10000, "taxed_value": 10000 - (10000 * 0.4), "in_ca": true } ม਺
78. mustacheه๏ͷجૅ mustache: Logic-less templates Hello {{name}} You have just won {{value}} dollars! {{#in_ca}} Well, {{taxed_value}} dollars, after taxes. {{/in_ca}} { "name": "Chris", "value": 10000, "taxed_value": 10000 - (10000 * 0.4), "in_ca": true } Ϧετ͔CPPM
79. mustacheه๏ͷجૅ mustache: Logic-less templates Hello {{name}} You have just won {{value}} dollars! {{#in_ca}} Well, {{taxed_value}} dollars, after taxes. {{/in_ca}} { "name": "Chris", "value": 10000, "taxed_value": 10000 - (10000 * 0.4), "in_ca": true } GBMTFͰ͸ͳ͍ɺ͔ͭɺ
    Ϧετ͕ۭͰ͸ͳ͍৔߹ʹ༗ޮ
80. ςϯϓϨʔτʹखΛՃ͑Δํ๏ swagger-codegen-cli generate \ -i swagger.yaml \ -l kotlin \ -t {ςϯϓϨʔτͷσΟϨΫτϦ}
81. ࣮ࡍʹςϯϓϨʔτ͚ͩΛ͍ͬͯ͡ɺ
    ,PUTIJʹରԠͯ͠ΈΑ͏ .PEFM͚ͩ
82. ΰʔϧ package io.swagger.client.models import io.swagger.client.models.Category import io.swagger.client.models.Tag data class Pet ( val name: kotlin.String, … ) {…
83. ΰʔϧ package io.swagger.client.models import io.swagger.client.models.Category import io.swagger.client.models.Tag import se.ansman.kotshi.JsonSerializable @JsonSerializable data class Pet ( val name: kotlin.String, … ) {…
84. ςϯϓϨʔτϑΝΠϧΛݟ͚ͭΔ 1. ςϯϓϨʔτϑΝΠϧΛݟ͚ͭΔ - kotlinͷ৔߹͸swagger-codegen/src/main/resources/ kotlin-client഑Լ 2. ςϯϓϨʔτϑΝΠϧΛ޷͖ͳ৔ॴʹίϐʔ - ͜ͷίϐʔͨ͠΋ͷΛฤू 3. ίϐʔͨ͠ϑΝΠϧ͔Β֘౰ϑΝΠϧΛݟ͚ͭͯฤू - data_class.mustache - enum_class.mustache - model.mustache - build.gradle.mustache 4. ੜ੒࣌ʹ -tΦϓγϣϯͰࢦఆ
85. data_class.mustache /** … */ @JsonSerializable data class {{classname}} ( {{#requiredVars}} {{>data_class_req_var}}{{^-last}}, {{/-last}}{{/requiredVars}}{{#hasRequired}}{{#hasOptional}}, {{/hasOptional}}{{/hasRequired}}{{#optionalVars}} {{>data_class_opt_var}}{{^-last}}, {{/-last}}{{/optionalVars}} ) …..
86. enum_class.mustache /** * {{{description}}} * Values: {{#allowableValues}}{{#enumVars}}{{&name}} {{^-last}},{{/-last}}{{/enumVars}}{{/allowableValues}} */ @JsonSerializable enum class {{classname}}(val value: {{dataType}}){ {{#allowableValues}}{{#enumVars}} {{&name}}({{{value}}}){{^-last}},{{/-last}}{{#-last}};{{/-last}} {{/enumVars}}{{/allowableValues}} }
87. model.mustache {{>licenseInfo}} package {{modelPackage}} {{#imports}}import {{import}} {{/imports}} import se.ansman.kotshi.JsonSerializable {{#models}} {{#model}} {{#isEnum}}{{>enum_class}}{{/isEnum}}{{^isEnum}}{{>data_class}} {{/isEnum}} {{/model}} {{/models}}
88. build.gradle.mustache dependencies { compile "org.jetbrains.kotlin:kotlin-stdlib- jre8:$kotlin_version" compile "com.squareup.moshi:moshi-kotlin:1.5.0" compile "com.squareup.moshi:moshi-adapters:1.5.0" compile "com.squareup.okhttp3:okhttp:3.8.0" compile 'se.ansman.kotshi:api:0.3.0' kapt 'se.ansman.kotshi:compiler:0.3.0' testCompile "io.kotlintest:kotlintest:2.0.2" }
89. ׬੒ʂ
90. ӡ༻্ͷ஫ҙ΍Φεεϝ͋Δʁ
91. Swagger Codegenͷิ଍৘ใ - ϦϦʔεαΠΫϧ͸ൺֱత஗ΊͳͷͰɺmasterϒϥϯνΛ ݟ͓ͯ͘ͷ΋Α͍͔΋ - Java͸ྑ͍ײ͕ͩ͡ɺKotlin͸·ͩൃల్্ - API෦෼͸RetrofitΛ࢖͍ͬͯΔΘ͚Ͱ΋ͳ͍ͷͰɺϞσ ϧΫϥεΛ࢖͑Δ͘Β͍ - ࠔͬͨΒࣗ෼ͰίϯτϦϏϡʔτ͢Δ͘Β͍ͷؾ࣋ͪͰ - ೔෇͕ java.time.LocalDateTimeܕݻఆͩͬͨͨΊɺ String΍ThreetenbpΛ࢖͑ΔΑ͏ʹίϯτϦϏϡʔτ ͨ͠
92. ॴײʢ·ͱΊʣ - ҉໧஌ͰऴΘΒͤͳ͍ͨΊʹɺSwaggerΛ༻͍͔ͯͬ͠ ΓAPIఆٛ͠ɺAPIఆٛͱ࣮૷Λܧଓతʹߋ৽͠ଓ͚Δ࢓ ૊ΈΛߟ͑Δ - ৽ن։ൃͷࡍɺAPIఆٛͱϞοΫαʔό͕͋Ε͹ɺαʔ όʔଆͱΞϓϦଆͷ։ൃεϐʔυ͕ҟͳͬͯ΋໰୊ͳ͍ - طଘͷϓϩδΣΫτͰ΋ಋೖϝϦοτ͸͋Δ - Swagger CodegenͷΧελϚΠζ΋Մೳ - Kotlinʹؔͯ͠͸ίϯτϦϏϡʔλʔ͕ඞཁͦ͏