Open API Specification を使ったスマートな API 運用
© 2016 KUFU, Inc. 0QFO"1*4QFDJpDBUJPOΛͬͨεϚʔτͳ"1*ӡ༻גࣜձࣾ,6'6۔ᖒխਓ݄"1*.FFUVQ
View Slide
© 2016 KUFU, Inc. ࣗݾհ۔ᖒ խਓ@masato_serizawa• גࣜձࣾ KUFU ΤϯδχΞ• ΤϯδχΞͱͯ͠ͷΩϟϦΞͷ΄ͱΜͲΛ WebAPI ͷઃܭɾ։ൃɾӡ༻ɾൢചΛͯ͠ա͍ͯ͝͠·͢• ͨ·ʹ Hackathon ʹग़ͨΓ͠·͢• झຯ Data Visualization Ͱ͢
ຊ͓͢Δ͜ͱʰ8FC"1*༷ॻͷӡ༻ʱ
© 2016 KUFU, Inc. ΞδΣϯμ•͕ࠓ·ͰؔΘ͖ͬͯͨ WebAPI ͱͦͷ՝•OpenAPI Specification ͕ղܾͯ͘͠ΕΔ͜ͱ•OpenAPI Specification ͷ࣮ફ•·ͱΊ
͕ࠓ·ͰؔΘ͖ͬͯͨ8FC"1*ͱͦͷ՝
© 2016 KUFU, Inc. WebAPI ͷӡ༻ʢ։ൃҎ֎ʣ•WebAPI ʹ I/F ༷ॻϦΫΤεταϯϓϧ͕͖ͷͰ͢•ઃܭɾ࣮ʹൺΔͱܰࢹ͞Ε͕ͪͰ͕͢ɺར༻ऀͷ UX ʹେ͖͘ӨڹΛ༩͑Δ෦Ͱ͋Γ·͢•ͦΕΒʹ͍ͭͯɺաڈʹܞΘͬͨ WebAPI ͔Βֶ͕Μͩ՝ཧ૾Λ͓͑͠·͢
$BTFᴈ໌ظͷ8FC"1*
© 2016 KUFU, Inc. Case1: ᴈ໌ظͷ WebAPIػೳ εϙοτݕࡧɺॅॴݕࡧɺFUD࣮ ॳ಄࣮ݴޠ +BWBར༻ϑϨʔϜϫʔΫಛʹͳ͠Ϩεϙϯεܗࣜ 9.-*'༷ॻ 8PSEجຊεϖοΫ
© 2016 KUFU, Inc. Case1: ᴈ໌ظͷ WebAPI•ϦΫΤεταϯϓϧ͕๛ʹ͋ͬͨ•HTML Ͱॻ͔Ε͍ͯͯɺϦϯΫΛԡ͢ͱϨεϙϯε͕֬ೝͰ͖Δ•ͲͷΑ͏ͳϦΫΤετύϥϝʔλ͕͋ͬͯɺͲͷΑ͏ͳϨεϙϯε͕͋Δͷ͔͕֬ೝ͍͢͠•ͪΐͬͱͨ͠ςετπʔϧʹͳΔ(PPE
© 2016 KUFU, Inc. Case1: ᴈ໌ظͷ WebAPI•༷ॻ͕͋·Γӡ༻͞Ε͍ͯͳ͔ͬͨ•ࣾϑΝΠϧڞ༗αʔόͷͲ͔͜ʹ͋Δ Word•هࡌͷൈ͚࿙Εཱ͕ͭ•࣮Λ֬ೝͨ͠ํ͕ૣ͍…•༷ͷ͍߹Θ͕ͤࡴ౸͢Δ1SPCMFN
© 2016 KUFU, Inc. Case1: ᴈ໌ظͷ WebAPI•༷ॻ͕͔ͬ͠Γ͍ͯ͠ͳ͍ͱ։ൃίετ͚ͩͰͳ͘ίϛϡχέʔγϣϯίετΕ্͕Δ•ઃܭࢥͷෆ౷Ұى͖͍͢•ʢΈԽ͠ͳ͍ͱʣਓ༷ॻΛඋ͠ͳ͍•WebAPI ϒϥβ্ͰαΫͬͱϨεϙϯενΣοΫͰ͖ΔͱḿΔֶ͕Μͩ͜ͱ
$BTFͪΐͬͱϞμϯͳ8FC"1*
© 2016 KUFU, Inc. Case2: ͪΐͬͱϞμϯͳ WebAPIػೳεϙοτݕࡧɺॅॴݕࡧɺFUDʢલड़"1*ͷϑϧεΫϥονϓϩμΫτʣ࣮ ࠒ࣮ݴޠ +BWBར༻ϑϨʔϜϫʔΫ8"'Ϩεϙϯεܗࣜ +40/*'༷ॻ 4QIJOYجຊεϖοΫ
© 2016 KUFU, Inc. Case2: ͪΐͬͱϞμϯͳ WebAPI•I/F ༷ॻΛ Sphinx Ͱ࡞͍ͯͨ͠•هड़ݴޠ rstʢreStructruedTextʣ•ιʔείʔυͱಉ͡ϦϙδτϦͰཧ•ϨϏϡʔରͱͳΔͨΊɺൈ͚࿙Ε͕গͳ͍•HTML PDF ʹมͰ͖ΔଞɺσβΠϯબͯඒ͍͠υΩϡϝϯτʹ্͕Δ(PPE
© 2016 KUFU, Inc. Case2: ͪΐͬͱϞμϯͳ WebAPI•༷ॻͷӡ༻ίετ͕গͳ͔Β͔͔ͣͬͨ•ΤϯυϙΠϯτΛՃ͢Δ࣌ͳͲ݁ߏͳίϐϖ࡞ۀ…•ϨεϙϯεαϯϓϧΛషΓ͚Δͷେม…•ΤϯλʔϓϥΠζ͚ʹผͰ༷ॻΛ༻ҙ͢ΔΑ͏ͳ߹ɺΠν͔Βॻ͖͢ඞཁ͕͋ͬͨ1SPCMFN
© 2016 KUFU, Inc. Case2: ͪΐͬͱϞμϯͳ WebAPI•៉ྷͳ༷ॻΛ࡞ΔͱتΕΔ•৺ͳ͔͍͠߹Θͤ༑తͳͷʹͳΔؾ͕͢Δ•༷ॻͱιʔείʔυ͚ۙΕ͍ۙ΄Ͳྑ͍•༷ॻ৭ʑͳϑΥʔϚοτͰͰ͖ΔͱḿΔ•༷ΛߏԽ͞ΕͨσʔλͰऔΕΔͱศརͦ͏ֶ͕Μͩ͜ͱ
·ͱΊΔͱʜ
© 2016 KUFU, Inc. ·ͱΊ•ਓ༷ॻΛඋ͠ͳ͍•ϨεϙϯενΣοΫ͕αΫͬͱग़དྷΔͱྑ͍•៉ྷͳ༷ॻΛ࡞Δͱ͍߹Θͤίετ͕ݮΔ•༷ॻͱιʔείʔυ͚ۙΕ͍ۙ΄Ͳྑ͍•༷ॻ༷ʑͳϑΥʔϚοτͰͰ͖Δͱྑ͍•༷ΛߏԽ͞ΕͨσʔλͰऔΕΔͱྑ͍
ҙ֎ͱߟྀ͕ଟ͍ʜʂ
0QFO"1*4QFDJpDBUJPO͕ղܾͯ͘͠ΕΔ͜ͱ
© 2016 KUFU, Inc. ͓͞Β͍•RESTful API Λهड़͢ΔͨΊͷ༷• ͕ Λϕʔεʹࡦఆ0QFO"1*4QFDJpDBUJPOͱ4XBHHFS3&45GVM"1*هड़༷ͷ΄͔͍͔ͭ͘ͷπʔϧ܈ʹΑͬͯߏ͞Ε͍ͯ·͢
© 2016 KUFU, Inc. جૅࣝ4XBHHFSͷߏ4XBHHFS$PSF8FC"1*ʹ࣮ʹଇͨ͠4XBHHFS4QFDΛฦ͢ΤϯυϙΠϯτΛੜ͢ϥΠϒϥϦ4XBHHFS6*4XBHHFS4QFDΛ͍͍ײ͡ʹϨϯμϦϯά͢Δ)5.-4XBHHFS4QFD4XBHHFSͷ༷ʹ४ͯ͡3&45"1*Λهड़ͨ͠+40/:.-ੜಡΈࠐΈ4XBHHFS&EJUPSϒϥβ্Ͱ4XBHHFS4QFDΛهड़͢Δπʔϧ3&45GVM"1*$MJFOU4%,ੜ
© 2016 KUFU, Inc. جૅࣝ4XBHHFSͷߏ4XBHHFS$PSF8FC"1*ʹ࣮ʹଇͨ͠4XBHHFS4QFDΛฦ͢ΤϯυϙΠϯτΛੜ͢ϥΠϒϥϦ4XBHHFS6*4XBHHFS4QFDΛ͍͍ײ͡ʹϨϯμϦϯά͢Δ)5.-4XBHHFS4QFD4XBHHFSͷ༷ʹ४ͯ͡3&45"1*Λهड़ͨ͠+40/:.-ੜಡΈࠐΈ4XBHHFS&EJUPSϒϥβ্Ͱ4XBHHFS4QFDΛهड़͢Δπʔϧ3&45GVM"1*$MJFOU4%,ੜ4XBHHFSͰ༷ॻΛੜ͢Δϑϩʔʹண͠·͢
© 2016 KUFU, Inc. Swagger Core + Swagger Spec + Swagger UIಋೖͷεςοϓ4UFQ4XBHHFS$PSFͷಋೖ4UFQ4XBHHFS4QFDͷ֬ೝ4UFQ4XBHHFS6*ͷಋೖw ϝδϟʔͳ8"'Ͱ͋ΕϥΠϒϥϦ͕͋Γ·͢w +BWBͩͱΞϊςʔγϣϯɺ3VCZͩͱ%4-Ͱ"1*Λهड़͍͖ͯ͠·͢w 4XBHHFS4QFDΛऔಘ͢ΔΤϯυϙΠϯτ͕ੜ͑·͢w )551(&5ͯ͠ϨεϙϯεΛ֬ೝͯ͠Έ·͠ΐ͏w 4XBHHFS6*Λμϯϩʔυ༷ͯ͠ॻΛදࣔͯ͠Έ·͠ΐ͏w ϥΠϒϥϦʹΑ༷ͬͯॻΛදࣔ͢ΔΤϯυϙΠϯτΛੜ͢ͷ͋Γ·͢
© 2016 KUFU, Inc. Swagger UI4XBHHFS6*
© 2016 KUFU, Inc. Swagger UI•Ξϊςʔγϣϯ DSL Ͱهड़ͨ͠ API ͷઆ໌͕៉ྷʹϨϯμϦϯά͞Ε·͢•ϥΠϒϥϦʹΑͬͯ Markdown Ͱॻ͘͜ͱՄೳ•τʔΫϯೝূͷػߏඋΘ͍ͬͯ·͢•ϦΫΤετύϥϝʔλͷઆ໌Λݟͳ͕Βɺ࣮ࡍʹΫΤϦΛߏஙͯ͠ϨεϙϯεΛ֬ೝͰ͖·͢
© 2016 KUFU, Inc. Swagger UI•Swagger UI γϯϓϧͳ HTML5 ͳͷͰɺϏϡʔൺֱత؆୯ʹΧελϚΠζՄೳͰ͢•৭ຯͳͲΛௐͨ͠ςʔϚެ։͞Ε͍ͯ·͢
ࠓ·Ͱͷ՝ͲͷΑ͏ʹղܾ͞ΕΔ͔
© 2016 KUFU, Inc. Swagger ͷಋೖʹΑΔ՝ղܾਓ༷ॻΛඋ͠ͳ͍࣮ʹଇ͢ΔͨΊ༰ৗʹ࠷৽ͷঢ়ଶͱͳΔϒϥβ্ͰϨεϙϯενΣοΫΛ͍ͨ͠4XBHHFS6*্ͰύϥϝʔλߏஙͱςετϦΫΤετ͕Մೳ៉ྷͳ༷ॻΛ࡞Δͱ͍߹Θͤίετ͕ݮΔσϑΥϧτͰͦͦ͜͜៉ྷʹͳΔɻඞཁʹԠͯ͡ΧελϚΠζՄೳ༷ॻͱιʔείʔυ͚ۙΕ͍ۙ΄Ͳྑ͍ιʔείʔυ্ʹهड़͞ΕΔ༷ॻ༷ʑͳϑΥʔϚοτͰͰ͖Δͱྑ͍ͦͷؾʹͳΕ4XBHHFS4QFDΛ1%'ͳͲมՄೳ༷ΛߏԽ͞ΕͨσʔλͰऔಘͰ͖Δͱྑ͍4XBHHFS4QFDΛ)551ͰऔಘՄೳ
ͳΜ͔ͩͱͯྑͦ͞͏ʜ
0QFO"1*4QFDJpDBUJPOͷ࣮ફ
4NBSU)3"1*
© 2016 KUFU, Inc. SmartHR APIػೳ 4NBSU)3ैۀһใͷݕࡧ࣮ ࣮ݴޠ 3VCZར༻ϑϨʔϜϫʔΫ(SBQFϨεϙϯεܗࣜ +40/*'༷ॻ 4XBHHFSجຊεϖοΫ
© 2016 KUFU, Inc. SmartHR API•ઌʹ WebAPI Λ࣮ͯ͠ɺޙ͔Β SwaggerSpec Λੜ͢ΔΞϓϩʔνΛͱΓ·ͨ͠•શʹ RESTful ͳઃܭͰɺτʔΫϯೝূ͋Γ·͢•Swagger UI ͔ͳΓΧελϚΠζͯ͋͠Γ·͢
© 2016 KUFU, Inc. SmartHR API4XBHHFS$PSF
© 2016 KUFU, Inc. SmartHR API4XBHHFS4QFD
© 2016 KUFU, Inc. SmartHR API4XBHHFS6*
ͳ͔ͳ͔ྑ্͍͕Γʂӡ༻ίετؾʹͳΒͳ͍
·ͱΊ
© 2016 KUFU, Inc. ·ͱΊ•OpenAPI Specification Λར༻͢ΔͱίετͰ͖ͪΜͱ༷ͨ͠ॻ͕࡞ΕΔ•ϦΫΤετνΣοΫπʔϧͱͯ͑͠Δ•༰͕Խ͢ΔϦεΫ͍•ར༻͍ͯ͠Δ WAF ʹରԠ͢ΔϥΠϒϥϦ͕͋Εಋೖൺֱత؆୯
0QFO"1*4QFDJpDBUJPOͰεϚʔτʹ"1*Λӡ༻͠·͠ΐ͏ʂ
ΤϯδχΞืूͯ͠·࠙͢ձͰ͓͠·͠ΐ͏ʂCFFSTw3VCZPO3BJMTw#͚4BB4wݹͯ͘ڊେͳ੍Λ)BDL͍ͨ͠w4NBSU)3"1*Λӡ༻͍ͨ͠