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

F958fbf402a67a1742335a4894e041e5?s=47 magiepooh
February 08, 2018

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

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

F958fbf402a67a1742335a4894e041e5?s=128

magiepooh

February 08, 2018
Tweet

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

  19. None
  20. "1*ͷϕʔε63-

  21. εΩʔϚ

  22. "1*ͷύε

  23. )551ϝιου

  24. CPEZͷఆٛ 1FUΦϒδΣΫτ

  25. Ϩεϙϯε

  26. EFpOJUJPOT

  27. None
  28. ඞਢ ϓϩύςΟ

  29. 4USJOHܕ FY EPHHJF

  30. UZQFͱGPSNBUͰܕ͕ܾ·Δ ˠMPOHܕ

  31. Swagger UI

  32. None
  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Λ ࢖Θͳ͔ͬͨͷʁ

  69. None
  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ʹؔͯ͠͸ίϯτϦϏϡʔλʔ͕ඞཁͦ͏
  93. None