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

by magiepooh

Slide 1

Slide 1 text

·ͩAPIఆٛ؅ཧͰফ໣ͯ͠Δͷʁ SwaggerΛ༻͍ͨ େن໛ΞϓϦ࣌୅ͷ APIఆٛ؅ཧͱίʔυδΣωϨʔτ 2018/2/8  #DroidKaigi

Slide 2

Slide 2 text

౻ాୖຏ Twitter: @magie_pooh GitHub: @magiepooh גࣜձࣾFOLIO झຯɾಛٕ:  ΫϥϑτϏʔϧɾ೔ຊञɾϚδοΫɾ࠵຾ ࣗݾ঺հ

Slide 3

Slide 3 text

˞ਤද΍σʔλ౳͸͋͘·Ͱ΋αϯϓϧͰ͋Γɺকདྷͷӡ༻੒Ռ౳Λࣔࠦ͋Δ͍͸อূ͢Δ΋ͷͰ͸͋Γ·ͤΜɻ

Slide 4

Slide 4 text

എܠ - ΞϓϦͰ࣮ݱ͍ͨ͜͠ͱ͕ෳࡶɾଟ༷Խ - αʔόʔͱΞϓϦΛ։ൃ͢ΔΤϯδχΞ͕ ผΕ͍ͯΔ͜ͱ͕ଟ͍ - ͦͷதͰɺεϐʔυΛอͬͨ։ൃ

Slide 5

Slide 5 text

ίϛϡχέʔγϣϯΛԁ׈ʹ ϛεΛىͣ͜͞ ਝ଎ʹ৘ใڞ༗

Slide 6

Slide 6 text

҉໧஌ͷܗࣜԽ - ҉໧஌ͷॻ͖ग़͠ - ࣄྫͷڞ༗

Slide 7

Slide 7 text

҉໧஌ͷܗࣜԽ - ҉໧஌ͷॻ͖ग़͠ → υΩϡϝϯτԽ - ࣄྫͷڞ༗ → αϯϓϧσʔλ

Slide 8

Slide 8 text

Έͳ͞Μɺ APIఆٛ؅ཧͯ͠·͔͢ʁ

Slide 9

Slide 9 text

APIఆٛͷϝϦοτ - ೝࣝͷᴥᴪΛͳ͘͢ - ৄࡉʹఆٛ͞Ε͍ͯΔͱɺؒҧ͍͕ى͖ʹ͍͘ - ख໭ΓΛͳ͘͢ ʢ˞ ϝϯς͠ଓ͚Δʣ

Slide 10

Slide 10 text

APIఆٛΛ؅ཧ͠Α͏

Slide 11

Slide 11 text

Ͳ͏΍ͬͯఆٛ͢Δʁ - Swagger - Protocol Buffers - api blueprint - Excel - ͦͷଞ

Slide 12

Slide 12 text

Ͳ͏΍ͬͯఆٛ͢Δʁ - Swagger - Protocol Buffers - api blueprint - Excel - ͦͷଞ

Slide 13

Slide 13 text

SwaggerΛ༻͍ͨ APIఆٛ

Slide 14

Slide 14 text

- The world’s Most Popular Framework for APIs - ϚΠΫϩιϑτɺGoogleɺIBMɺIntuitɺ PayPalɺ3ScaleɺApigeeɺCapital Oneɺ RestletɺSmartBear্ཱ͕ͪ͛ͨOpenAPI Initiativ͕APIهड़ͷͨΊʹSwaggerΛ࠾༻ Swagger

Slide 15

Slide 15 text

- REST APIͷઃܭ͔ΒυΩϡϝϯτԽɺςετɺ σϓϩΠ·ͰΛΧόʔ - APIఆٛ - Blueprint(ϞοΫ) - Codegen Swagger

Slide 16

Slide 16 text

͜͜ʹςΩετΛೖΕ·͢ɻ ͻͱͭͷεϥΠυʹ಺༰Λ٧Ί͗͢ͳ͍Α͏ʹ͠·͠ΐ͏ɻ Կ౓΋͏Δ͍͞Α͏Ͱ͕͢ʮ̍ຕͷεϥΠυʹ̍ͭͷҙຯʯ ͕εϥΠυ࡞ΓͷجຊͰ͢ɻ 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

Slide 17

Slide 17 text

Swagger Editor

Slide 18

Slide 18 text

APIఆٛΛϨϯμϦϯά͠ͳ͕Βɺฤू͢Δ͜ͱ͕Ͱ͖Δ OnlineEditor https://swagger.io/swagger-editor/ Swagger Editor

Slide 19

Slide 19 text

No content

Slide 20

Slide 20 text

"1*ͷϕʔε63-

Slide 21

Slide 21 text

εΩʔϚ

Slide 22

Slide 22 text

"1*ͷύε

Slide 23

Slide 23 text

)551ϝιου

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Ϩεϙϯε

Slide 26

Slide 26 text

EFpOJUJPOT

Slide 27

Slide 27 text

No content

Slide 28

Slide 28 text

ඞਢ ϓϩύςΟ

Slide 29

Slide 29 text

4USJOHܕ FY EPHHJF

Slide 30

Slide 30 text

UZQFͱGPSNBUͰܕ͕ܾ·Δ ˠMPOHܕ

Slide 31

Slide 31 text

Swagger UI

Slide 32

Slide 32 text

No content

Slide 33

Slide 33 text

APIΛఆٛͯ͠΋ɺ ࣮૷ΛϛεΔͱ͖͸ ϛεΔΑͶʁ

Slide 34

Slide 34 text

ίʔυ͸ ػցతʹੜ੒͠Α͏

Slide 35

Slide 35 text

Swagger Codegen

Slide 36

Slide 36 text

Swagger Codgenͱ͸ - SwaggerͰఆٛͨ͠ϑΝΠϧ͔Βɺίʔυ΍ υΩϡϝϯτΛࣗಈੜ੒ - ΫϥΠϯτ - Model - Api - Docs

Slide 37

Slide 37 text

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, Retroﬁt1.x, Retroﬁt2.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

Slide 38

Slide 38 text

ػցతʹੜ੒͢Δ͜ͱʹΑͬͯ - ޻਺࡟ݮ - JSONͷϚοϐϯάΦϒδΣΫτΛखॻ͖͢ Δͷ͸ਏ͍ - ਓҝతϛεͷհೖΛڐ͞ͳ͍ - ςετ͢΂͖ର৅͕ݮΔ - υΩϡϝϯτ࡞੒ऀͷҙਤ௨Γͷ࣮૷ʹͳΔ - ҙਤͷဃ཭Λͳ͘͢

Slide 39

Slide 39 text

swagger-codegen-cli generate \ -i swagger.yaml \ -l kotlin -i : input ﬁle -l : language ੜ੒ํ๏

Slide 40

Slide 40 text

Model

Slide 41

Slide 41 text

API(Kotlin) ,PUMJO͸ಠࣗͷ࣮૷ʹͳ͍ͬͯΔ

Slide 42

Slide 42 text

API(Java:Retroﬁt+Rx) +BWB͸3Y+BWB 3FUSPpU͕αϙʔτ͞Ε͍ͯΔ ˠ"1*ʹؔͯ͠͸,PUMJO͸࢖͍ʹ͍͘ɾɾ

Slide 43

Slide 43 text

Docs(API)

Slide 44

Slide 44 text

Docs(Model)

Slide 45

Slide 45 text

Swagger CodegenͰ ϞοΫαʔό΋࡞ΕΔ

Slide 46

Slide 46 text

Swagger Editor͔Β

Slide 47

Slide 47 text

ϞοΫαʔόΛίϚϯυ͔Β࡞੒ swagger-codegen generate \ -i petstore.yaml -l nodejs-server ͜ΕͰNode.jsͷίʔυ͕ੜ੒͞ΕΔͷͰɺ͋ ͱ͸্ཱͪ͛Δ͚ͩ

Slide 48

Slide 48 text

ϞοΫαʔόͷϝϦοτ - ΞϓϦͰ࢖༻͍ͯ͠ΔAPIఆٛͷόʔδϣϯͱ ϞοΫαʔόͷόʔδϣϯΛ߹Θ͓ͤͯ͘ͱɺ αʔόଆͷ։ൃ଎౓ʹؔ܎ͳ͘ΞϓϦ։ൃऀ ͷ։ൃεϐʔυͰରԠՄೳ - ৗʹ৽͍͠ϞοΫαʔόΛ࢖͏ඞཁ͸ͳ͍ - ΞϓϦͰఆٛΛ൓өͨ͠Βɺ্ཱͪ͛ΔϞο ΫαʔόΛม͑Ε͹ྑ͍ - αʔόʔΤϯδχΞʹ଴ͬͯ΋Β͏ඞཁͳ͠

Slide 49

Slide 49 text

ϞοΫαʔόͷσϝϦοτ - ϦετͷΞΠςϜ਺͸ৗʹ̍ͭ

Slide 50

Slide 50 text

࣮ࡍͷӡ༻

Slide 51

Slide 51 text

Q.FOLIOͰͲ͏΍ͬͯ ӡ༻͍ͯ͠Δͷʁ

Slide 52

Slide 52 text

FOLIO͸ϚΠΫϩαʔϏεΞʔΩςΫνϟ #'' .JDSPTFSWJDF .JDSPTFSWJDF .JDSPTFSWJDF .JDSPTFSWJDF "OESPJE J04 #''͸.JDSP4FSWJDF܊ͱ ಠཱͯ͠ϑϩϯτدΓɻ #''Λ։ൃ͢Δਓͱ ΞϓϦΤϯδχΞͷίϛϡχέʔγϣϯɻ

Slide 53

Slide 53 text

ӡ༻ํ๏ #'' #''୲౰͕σβΠϯΛݟͯɺ"1*ఆٛΛ࡞ͬͯ13 "1*ఆٛ͜ΜͳͷͲ͏ʁ 13 "OESPJE J04

Slide 54

Slide 54 text

ӡ༻ํ๏ #'' ΞϓϦଆ΋ؚΊͯϨϏϡʔ "1*ఆٛ͜ΜͳͷͲ͏ʁ Αͦ͞͏ʂ  ͜ͷΦϒδΣΫτɺ ଞͷ"1*ͱڞ௨ԽͰ͖Δ͔΋ʁ 13 3FWJFX "OESPJE J04

Slide 55

Slide 55 text

ӡ༻ํ๏ #'' ໰୊΍վળ͕͋Ε͹ɺ ΞϓϦଆ͔Β*TTVF΍13Ͱٞ࿦ ͜Μͳײ͡ʹ͍ͨ͠ʂ *TTVF13 "OESPJE J04

Slide 56

Slide 56 text

ӡ༻ํ๏ #'' ໰୊΍վળ͕͋Ε͹ɺ ΞϓϦଆ͔Β*TTVF΍13Ͱٞ࿦ -(5. ͜Μͳײ͡ʹ͍ͨ͠ʂ *TTVF13 3FWJFX "OESPJE J04

Slide 57

Slide 57 text

ӡ༻ํ๏ - masterʹϚʔδޙɺλάΛ੾Δ - ֘౰ͷλάΛsubmoduleͱͯ͠ࢀর͢Δ - ʢຊ౰͸͍Ζ͍Ζ͍͕ͨ͠ɺ࡯͍ͯͩ͘͠͞ʣ - BFF͸ϑϩϯτʹґଘͯ͠Α͍ͷͰɺΞϓϦଆͷ ࢖͍΍͍͢Α͏ʹఆٛ͠ɺGitHub্Ͱٞ࿦͢Δ

Slide 58

Slide 58 text

Q.1ͭͷYAMLϑΝΠϧͰ؅ཧ ͢Δͷ͸ਏ͘ͳ͍ʁ

Slide 59

Slide 59 text

ͭΒ͍

Slide 60

Slide 60 text

̍ͭͷyamlϑΝΠϧʹ͢΂ͯఆٛ͢Δͷ͸ਏ͍ͷ Ͱɺฤू࣌͸ϑΝΠϧ෼ׂͯ͠ఆٛ͠ɺϏϧυ࣌ʹ ݁߹͢Δɻ → multi-ﬁle-swaggerΛ༻͍Δ ࣮ࡍʹఆٛ͢Δํ๏

Slide 61

Slide 61 text

multi-ﬁle-swagger

Slide 62

Slide 62 text

multi-ﬁle-swagger

Slide 63

Slide 63 text

$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

Slide 64

Slide 64 text

Q. APIఆٛͷ όϦσʔτ͸Ͳ͏ͯ͠Δʁ

Slide 65

Slide 65 text

$npm install swagger-cli $swagger validate compiled.yml https://www.npmjs.com/package/swagger-cli pre-commitͰcompileͱvalidate͕૸ΔΑ͏ʹ͠ ͓ͯ͘ swagger-cli

Slide 66

Slide 66 text

Q. gRPC+Protocol BuffersΛ ࢖͍ͬͯΔ͔Βɺ Swagger͸ඞཁͳ͍ʁ

Slide 67

Slide 67 text

.protoϑΝΠϧ͔Β.javaϑΝΠϧΛੜ੒Մೳͳͷ ͰɺCodegen͸ඞཁͳ͍ɻ ͕ɺSwagger༻ͷJSONఆٛ΋ు͖ग़ͤΔͷͰɺ SwaggerUIͰυΩϡϝϯτͷڞ༗͸Մೳɻ →Swagger͸࢖͑ΔൣғͰ࢖͑͹ྑ͍ Codegen͸ඞཁͳ͍͕ɺSwaggerUI͸࢖͑Δ

Slide 68

Slide 68 text

Q. ͳͥFOLIO͸ gRPC + ProtocolBuffersΛ ࢖Θͳ͔ͬͨͷʁ

Slide 69

Slide 69 text

No content

Slide 70

Slide 70 text

ཧ༝͸લํ/ޙํޓ׵ੑΛอͭͨΊɻ 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; }

Slide 71

Slide 71 text

- BFFͱ͍͏ଘࡏ͕͋ΔͨΊɺ͕ͬͪΓܕ͕͋Δํ ͕ϝϦοτେ͖͔ͬͨ - APIఆٛͷޙํޓ׵ੑ͸ͳͯ͘΋Α͍ - swaggerͷbasePathΛv1, v2ͷΑ͏ʹରԠ →ࠓճ͸࢖Θͳͯ͘΋Α͍͔ͳɾɾ ʢݸਓతʹ͸࢖͍͍ͨʣ proto3Λ࢖Θͳ͔ͬͨཧ༝

Slide 72

Slide 72 text

ಋೖͯ͠Α͔ͬͨ͜ͱ͸ʁ

Slide 73

Slide 73 text

ಋೖͷར఺ - BFF؍఺ - Flowtypeͷܕ͕ੜ੒Ͱ͖ͯյΕʹ͍͘ - BFFͷઃܭͱflowtype / @KeitaMoromizato - https://qiita.com/KeitaMoromizato/items/d749d472f60ba4031b69 - iOS؍఺ - API, ModelΫϥε·Ͱࣗಈੜ੒ - KotlinΑΓ΋͞Βʹଟ͘ͷΫϥε͕ϓϩδΣΫτʹಋೖՄೳͳϨ ϕϧ - SwaggerͰ࢝ΊΔAPIఆٛ؅ཧͱίʔυδΣωϨʔτ/ਿ্ ༸ฏ - https://www.youtube.com/watch?v=agZ6T72lXzo

Slide 74

Slide 74 text

Q. ΧελϚΠζ ͍ͨ͠Μ͚ͩͲɺ Ͱ͖Δʁ

Slide 75

Slide 75 text

Ͱ͖·͢

Slide 76

Slide 76 text

- JavaͰॻ͔ΕͨXxxClientCodegen - ֤ݴޠͷܕΛܾΊΔ - ΦϓγϣϯͷॲཧͳͲͳͲ - mustacheه๏Ͱهड़͞ΕͨςϯϓϨʔτ - ClientCodegenͰ౉͞Εͨ஋ΛϚοϐϯά → ClientCodegen͔ɺςϯϓϨʔτʹखΛՃ͑Δ Swaggerͷߏ੒

Slide 77

Slide 77 text

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 } ม਺

Slide 78

Slide 78 text

Slide 79

Slide 79 text

Slide 80

Slide 80 text

ςϯϓϨʔτʹखΛՃ͑Δํ๏ swagger-codegen-cli generate \ -i swagger.yaml \ -l kotlin \ -t {ςϯϓϨʔτͷσΟϨΫτϦ}

Slide 81

Slide 81 text

࣮ࡍʹςϯϓϨʔτ͚ͩΛ͍ͬͯ͡ɺ ,PUTIJʹରԠͯ͠ΈΑ͏ .PEFM͚ͩ

Slide 82

Slide 82 text

ΰʔϧ package io.swagger.client.models import io.swagger.client.models.Category import io.swagger.client.models.Tag data class Pet ( val name: kotlin.String, … ) {…

Slide 83

Slide 83 text

ΰʔϧ 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, … ) {…

Slide 84

Slide 84 text

ςϯϓϨʔτϑΝΠϧΛݟ͚ͭΔ 1. ςϯϓϨʔτϑΝΠϧΛݟ͚ͭΔ - kotlinͷ৔߹͸swagger-codegen/src/main/resources/ kotlin-client഑Լ 2. ςϯϓϨʔτϑΝΠϧΛ޷͖ͳ৔ॴʹίϐʔ - ͜ͷίϐʔͨ͠΋ͷΛฤू 3. ίϐʔͨ͠ϑΝΠϧ͔Β֘౰ϑΝΠϧΛݟ͚ͭͯฤू - data_class.mustache - enum_class.mustache - model.mustache - build.gradle.mustache 4. ੜ੒࣌ʹ -tΦϓγϣϯͰࢦఆ

Slide 85

Slide 85 text

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}} ) …..

Slide 86

Slide 86 text

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}} }

Slide 87

Slide 87 text

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}}

Slide 88

Slide 88 text

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" }

Slide 89

Slide 89 text

׬੒ʂ

Slide 90

Slide 90 text

ӡ༻্ͷ஫ҙ΍Φεεϝ͋Δʁ

Slide 91

Slide 91 text

Swagger Codegenͷิ଍৘ใ - ϦϦʔεαΠΫϧ͸ൺֱత஗ΊͳͷͰɺmasterϒϥϯνΛ ݟ͓ͯ͘ͷ΋Α͍͔΋ - Java͸ྑ͍ײ͕ͩ͡ɺKotlin͸·ͩൃల్্ - API෦෼͸RetrofitΛ࢖͍ͬͯΔΘ͚Ͱ΋ͳ͍ͷͰɺϞσ ϧΫϥεΛ࢖͑Δ͘Β͍ - ࠔͬͨΒࣗ෼ͰίϯτϦϏϡʔτ͢Δ͘Β͍ͷؾ࣋ͪͰ - ೔෇͕ java.time.LocalDateTimeܕݻఆͩͬͨͨΊɺ String΍ThreetenbpΛ࢖͑ΔΑ͏ʹίϯτϦϏϡʔτ ͨ͠

Slide 92

Slide 92 text

ॴײʢ·ͱΊʣ - ҉໧஌ͰऴΘΒͤͳ͍ͨΊʹɺSwaggerΛ༻͍͔ͯͬ͠ ΓAPIఆٛ͠ɺAPIఆٛͱ࣮૷Λܧଓతʹߋ৽͠ଓ͚Δ࢓ ૊ΈΛߟ͑Δ - ৽ن։ൃͷࡍɺAPIఆٛͱϞοΫαʔό͕͋Ε͹ɺαʔ όʔଆͱΞϓϦଆͷ։ൃεϐʔυ͕ҟͳͬͯ΋໰୊ͳ͍ - طଘͷϓϩδΣΫτͰ΋ಋೖϝϦοτ͸͋Δ - Swagger CodegenͷΧελϚΠζ΋Մೳ - Kotlinʹؔͯ͠͸ίϯτϦϏϡʔλʔ͕ඞཁͦ͏

Slide 93

Slide 93 text

No content