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

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