API Meetup #15

Open API Specification を使ったスマートな API 運用

1. © 2016 KUFU, Inc.  0QFO"1*
   4QFDJpDBUJPO
   Λ࢖ͬͨ
   εϚʔτͳ
   "1*
   ӡ༻ גࣜձࣾ,6'6
   ۔ᖒ
   խਓ
   ೥݄೔
   "1*
   .FFUVQ
   
2. © 2016 KUFU, Inc.  ࣗݾ঺հ ۔ᖒ խਓ @masato_serizawa • גࣜձࣾ KUFU ΤϯδχΞ • ΤϯδχΞͱͯ͠ͷΩϟϦΞͷ΄ͱΜͲΛ WebAPI ͷઃܭɾ ։ൃɾӡ༻ɾൢചΛͯ͠ա͍ͯ͝͠·͢ • ͨ·ʹ Hackathon ʹग़ͨΓ͠·͢ • झຯ͸ Data Visualization Ͱ͢
3. ຊ೔͓࿩͢Δ͜ͱʰ8FC"1*
   ࢓༷ॻͷӡ༻ʱ
4. © 2016 KUFU, Inc.  ΞδΣϯμ •๻͕ࠓ·ͰؔΘ͖ͬͯͨ WebAPI ͱͦͷ՝୊ •OpenAPI Specification ͕ղܾͯ͘͠ΕΔ͜ͱ •OpenAPI Specification ͷ࣮ફ •·ͱΊ
5. ๻͕ࠓ·ͰؔΘ͖ͬͯͨ
   8FC"1*
   ͱͦͷ՝୊
6. © 2016 KUFU, Inc.  WebAPI ͷӡ༻ʢ։ൃҎ֎ʣ •WebAPI ʹ͸ I/F ࢓༷ॻ΍ϦΫΤεταϯϓϧ ͕෇͖΋ͷͰ͢ •ઃܭɾ࣮૷ʹൺ΂Δͱܰࢹ͞Ε͕ͪͰ͕͢ɺར ༻ऀͷ UX ʹେ͖͘ӨڹΛ༩͑Δ෦෼Ͱ΋͋Γ ·͢ •ͦΕΒʹ͍ͭͯɺաڈʹܞΘͬͨ WebAPI ͔Β ๻ֶ͕Μͩ՝୊΍ཧ૝૾Λ͓఻͑͠·͢
7. $BTF
   ᴈ໌ظͷ
   8FC"1*
8. © 2016 KUFU, Inc.  Case1: ᴈ໌ظͷ WebAPI ػೳ εϙοτݕࡧɺॅॴݕࡧɺFUD ࣮૷೥୅ ೥୅ॳ಄ ࣮૷ݴޠ +BWB ར༻
   ϑϨʔϜϫʔΫ ಛʹͳ͠ Ϩεϙϯεܗࣜ 9.- *'
   ࢓༷ॻ 8PSE 
   جຊεϖοΫ
9. © 2016 KUFU, Inc.  Case1: ᴈ໌ظͷ WebAPI •ϦΫΤεταϯϓϧ͕๛෋ʹ͋ͬͨ •HTML Ͱॻ͔Ε͍ͯͯɺϦϯΫΛԡ͢ͱϨεϙ ϯε͕֬ೝͰ͖Δ •ͲͷΑ͏ͳϦΫΤετύϥϝʔλ͕͋ͬͯɺͲ ͷΑ͏ͳϨεϙϯε͕͋Δͷ͔͕֬ೝ͠΍͍͢ •ͪΐͬͱͨ͠ςετπʔϧʹ΋ͳΔ 
   (PPE
10. © 2016 KUFU, Inc.  Case1: ᴈ໌ظͷ WebAPI •࢓༷ॻ͕͋·Γӡ༻͞Ε͍ͯͳ͔ͬͨ •ࣾ಺ϑΝΠϧڞ༗αʔόͷͲ͔͜ʹ͋Δ Word •هࡌͷൈ͚࿙Ε͕໨ཱͭ •࣮૷Λ֬ೝͨ͠ํ͕ૣ͍… •࢓༷ͷ໰͍߹Θ͕ͤࡴ౸͢Δ 
    1SPCMFN
11. © 2016 KUFU, Inc.  Case1: ᴈ໌ظͷ WebAPI •࢓༷ॻ͕͔ͬ͠Γ͍ͯ͠ͳ͍ͱ։ൃίετ͚ͩ Ͱͳ͘ίϛϡχέʔγϣϯίετ΋๲Ε্͕Δ •ઃܭࢥ૝ͷෆ౷Ұ΋ى͖΍͍͢ •ʢ࢓૊ΈԽ͠ͳ͍ͱʣਓ͸࢓༷ॻΛ੔උ͠ͳ͍ •WebAPI ͸ϒϥ΢β্ͰαΫͬͱϨεϙϯε νΣοΫͰ͖ΔͱḿΔ 
    ๻ֶ͕Μͩ͜ͱ
12. $BTF
    ͪΐͬͱϞμϯͳ
    8FC"1*
13. © 2016 KUFU, Inc.  Case2: ͪΐͬͱϞμϯͳ WebAPI ػೳ εϙοτݕࡧɺॅॴݕࡧɺFUD
    ʢલड़
    "1*
    ͷϑϧεΫϥονϓϩμΫτʣ ࣮૷೥୅ ೥ࠒ ࣮૷ݴޠ +BWB ར༻
    ϑϨʔϜϫʔΫ ಺੡
    8"' Ϩεϙϯεܗࣜ +40/ *'
    ࢓༷ॻ 4QIJOY 
    جຊεϖοΫ
14. © 2016 KUFU, Inc.  Case2: ͪΐͬͱϞμϯͳ WebAPI •I/F ࢓༷ॻΛ Sphinx Ͱ࡞੒͍ͯͨ͠ •هड़ݴޠ͸ rstʢreStructruedTextʣ •ιʔείʔυͱಉ͡ϦϙδτϦͰ؅ཧ •ϨϏϡʔର৅ͱͳΔͨΊɺൈ͚࿙Ε͕গͳ͍ •HTML ΍ PDF ʹม׵Ͱ͖ΔଞɺσβΠϯ΋બ ΂ͯඒ͍͠υΩϡϝϯτʹ࢓্͕Δ 
    (PPE
15. © 2016 KUFU, Inc.  Case2: ͪΐͬͱϞμϯͳ WebAPI •࢓༷ॻͷӡ༻ίετ͕গͳ͔Β͔͔ͣͬͨ •ΤϯυϙΠϯτΛ௥Ճ͢Δ࣌ͳͲ͸݁ߏͳίϐ ϖ࡞ۀ… •ϨεϙϯεαϯϓϧΛషΓ෇͚Δͷେม… •ΤϯλʔϓϥΠζ޲͚ʹผͰ࢓༷ॻΛ༻ҙ͢Δ Α͏ͳ৔߹͸ɺΠν͔Βॻ͖௚͢ඞཁ͕͋ͬͨ 
    1SPCMFN
16. © 2016 KUFU, Inc.  Case2: ͪΐͬͱϞμϯͳ WebAPI •៉ྷͳ࢓༷ॻΛ࡞Δͱت͹ΕΔ •৺ͳ͔͠໰͍߹Θͤ΋༑޷తͳ΋ͷʹͳΔؾ͕ ͢Δ •࢓༷ॻͱιʔείʔυ͸͚ۙΕ͹͍ۙ΄Ͳྑ͍ •࢓༷ॻ͸৭ʑͳϑΥʔϚοτͰ഑෍Ͱ͖Δͱḿ Δ •࢓༷Λߏ଄Խ͞ΕͨσʔλͰऔΕΔͱศརͦ͏ 
    ๻ֶ͕Μͩ͜ͱ
17. ·ͱΊΔͱʜ
18. © 2016 KUFU, Inc.  ·ͱΊ •ਓ͸࢓༷ॻΛ੔උ͠ͳ͍ •ϨεϙϯενΣοΫ͕αΫͬͱग़དྷΔͱྑ͍ •៉ྷͳ࢓༷ॻΛ࡞Δͱ໰͍߹Θͤίετ͕ݮΔ •࢓༷ॻͱιʔείʔυ͸͚ۙΕ͹͍ۙ΄Ͳྑ͍ •࢓༷ॻ͸༷ʑͳϑΥʔϚοτͰ഑෍Ͱ͖Δͱྑ ͍ •࢓༷Λߏ଄Խ͞ΕͨσʔλͰऔΕΔͱྑ͍
19. ҙ֎ͱߟྀ఺͕ଟ͍ʜʂ
20. 0QFO"1*
    4QFDJpDBUJPO
    ͕
    ղܾͯ͘͠ΕΔ͜ͱ
21. © 2016 KUFU, Inc.  ͓͞Β͍ •RESTful API Λهड़͢ΔͨΊͷ࢓༷ • ͕ Λϕʔεʹࡦఆ 
    0QFO"1*
    4QFDJpDBUJPO
    ͱ͸ 4XBHHFS
    ͸
    3&45GVM
    "1*
    هड़࢓༷ͷ΄͔
    ͍͔ͭ͘ͷπʔϧ܈ʹΑͬͯߏ੒͞Ε͍ͯ·͢
22. © 2016 KUFU, Inc.  جૅ஌ࣝ 
    4XBHHFS
    ͷߏ੒ 4XBHHFS
    $PSF
    8FC"1*
    ʹ࣮૷ʹଇͨ͠
    4XBHHFS4QFD
    Λฦ͢Τϯυ ϙΠϯτΛੜ΍͢ϥΠϒϥϦ 4XBHHFS
    6*
    4XBHHFS
    4QFD
    Λ͍͍ײ͡ʹ ϨϯμϦϯά͢Δ
    )5.- 4XBHHFS
    4QFD
    4XBHHFS
    ͷ࢓༷ʹ४ͯ͡
    3&45
    "1*
    Λهड़ͨ͠
    +40/
    
    :.- ੜ੒ ಡΈࠐΈ 4XBHHFS
    &EJUPS
    ϒϥ΢β্Ͱ
    4XBHHFS
    4QFD
    Λهड़͢Δπʔϧ 3&45GVM
    "1* $MJFOU
    4%, ੜ੒
23. © 2016 KUFU, Inc.  جૅ஌ࣝ 
    4XBHHFS
    ͷߏ੒ 4XBHHFS
    $PSF
    8FC"1*
    ʹ࣮૷ʹଇͨ͠
    4XBHHFS4QFD
    Λฦ͢Τϯυ ϙΠϯτΛੜ΍͢ϥΠϒϥϦ 4XBHHFS
    6*
    4XBHHFS
    4QFD
    Λ͍͍ײ͡ʹ ϨϯμϦϯά͢Δ
    )5.- 4XBHHFS
    4QFD
    4XBHHFS
    ͷ࢓༷ʹ४ͯ͡
    3&45
    "1*
    Λهड़ͨ͠
    +40/
    
    :.- ੜ੒ ಡΈࠐΈ 4XBHHFS
    &EJUPS
    ϒϥ΢β্Ͱ
    4XBHHFS
    4QFD
    Λهड़͢Δπʔϧ 3&45GVM
    "1* $MJFOU
    4%, ੜ੒ 4XBHHFS
    Ͱ࢓༷ॻΛੜ੒͢Δϑϩʔʹண໨͠·͢
24. © 2016 KUFU, Inc.  Swagger Core + Swagger Spec + Swagger UI 
    ಋೖͷεςοϓ 4UFQ
    4XBHHFS
    $PSF
    ͷಋೖ 4UFQ
    4XBHHFS
    4QFD
    ͷ֬ೝ 4UFQ
    4XBHHFS
    6*
    ͷಋೖ w ϝδϟʔͳ
    8"'
    Ͱ͋ Ε͹ϥΠϒϥϦ͕͋Γ ·͢
    w +BWB
    ͩͱΞϊςʔγϣ ϯɺ3VCZ
    ͩͱ
    %4-
    Ͱ
    "1*
    Λهड़͍͖ͯ͠· ͢ w 4XBHHFS
    4QFD
    Λऔಘ ͢ΔΤϯυϙΠϯτ͕ ੜ͑·͢
    w )551
    (&5
    ͯ͠Ϩεϙ ϯεΛ֬ೝͯ͠Έ·͠ΐ ͏ w 4XBHHFS
    6*
    Λμ΢ϯ ϩʔυͯ͠࢓༷ॻΛද ࣔͯ͠Έ·͠ΐ͏
    w ϥΠϒϥϦʹΑͬͯ͸ ࢓༷ॻΛදࣔ͢ΔΤϯ υϙΠϯτΛੜ΍͢΋ ͷ΋͋Γ·͢
25. © 2016 KUFU, Inc.  Swagger UI 
    4XBHHFS
    6*
26. © 2016 KUFU, Inc.  Swagger UI •Ξϊςʔγϣϯ΍ DSL Ͱهड़ͨ͠ API ͷઆ໌͕ ៉ྷʹϨϯμϦϯά͞Ε·͢ •ϥΠϒϥϦʹΑͬͯ͸ Markdown Ͱॻ͘͜ͱ ΋Մೳ •τʔΫϯೝূͷػߏ΋උΘ͍ͬͯ·͢ •ϦΫΤετύϥϝʔλͷઆ໌Λݟͳ͕Βɺ࣮ࡍ ʹΫΤϦΛߏஙͯ͠ϨεϙϯεΛ֬ೝͰ͖·͢
27. © 2016 KUFU, Inc.  Swagger UI •Swagger UI ͸γϯϓϧͳ HTML5 ͳͷͰɺ Ϗϡʔ͸ൺֱత؆୯ʹΧελϚΠζՄೳͰ͢ •৭ຯͳͲΛௐ੔ͨ͠ςʔϚ΋ެ։͞Ε͍ͯ·͢
28. ࠓ·Ͱͷ՝୊͸
    ͲͷΑ͏ʹղܾ͞ΕΔ͔
29. © 2016 KUFU, Inc.  Swagger ͷಋೖʹΑΔ՝୊ղܾ ਓ͸࢓༷ॻΛ੔උ͠ͳ͍ ࣮૷ʹଇ͢ΔͨΊ಺༰͸
    ৗʹ࠷৽ͷঢ়ଶͱͳΔ ϒϥ΢β্Ͱ
    ϨεϙϯενΣοΫΛ͍ͨ͠ 4XBHHFS
    6*
    ্Ͱύϥϝʔλߏஙͱ
    ςετϦΫΤετ͕Մೳ ៉ྷͳ࢓༷ॻΛ࡞Δͱ
    ໰͍߹Θͤίετ͕ݮΔ σϑΥϧτͰ΋ͦͦ͜͜៉ྷʹͳΔɻ
    ඞཁʹԠͯ͡ΧελϚΠζՄೳ ࢓༷ॻͱιʔείʔυ͸
    ͚ۙΕ͹͍ۙ΄Ͳྑ͍ ιʔείʔυ্ʹهड़͞ΕΔ ࢓༷ॻ͸༷ʑͳϑΥʔϚοτͰ
    ഑෍Ͱ͖Δͱྑ͍ ͦͷؾʹͳΕ͹
    4XBHHFS
    4QFD
    Λ
    1%'
    ͳͲ΁ม׵Մೳ ࢓༷Λߏ଄Խ͞ΕͨσʔλͰ
    औಘͰ͖Δͱྑ͍ 4XBHHFS
    4QFD
    Λ
    )551
    ͰऔಘՄೳ
30. ͳΜ͔ͩͱͯ΋ྑͦ͞͏ʜ
31. 0QFO"1*
    4QFDJpDBUJPO
    ͷ࣮ફ
32. 4NBSU)3
    "1*
33. © 2016 KUFU, Inc.  SmartHR API ػೳ 4NBSU)3
    ैۀһ৘ใͷݕࡧ ࣮૷೥୅ ೥ ࣮૷ݴޠ 3VCZ ར༻
    ϑϨʔϜϫʔΫ (SBQF Ϩεϙϯεܗࣜ +40/ *'
    ࢓༷ॻ 4XBHHFS 
    جຊεϖοΫ
34. © 2016 KUFU, Inc.  SmartHR API •ઌʹ WebAPI Λ࣮૷ͯ͠ɺޙ͔Β Swagger Spec Λੜ੒͢ΔΞϓϩʔνΛͱΓ·ͨ͠ •׬શʹ RESTful ͳઃܭͰɺτʔΫϯೝূ΋͋Γ ·͢ •Swagger UI ͸͔ͳΓΧελϚΠζͯ͋͠Γ·͢
35. © 2016 KUFU, Inc.  SmartHR API 
    4XBHHFS
    $PSF
36. © 2016 KUFU, Inc.  SmartHR API 
    4XBHHFS
    4QFD
37. © 2016 KUFU, Inc.  SmartHR API 
    4XBHHFS
    6*
38. ͳ͔ͳ͔ྑ͍࢓্͕Γʂ
    ӡ༻ίετ΋ؾʹͳΒͳ͍
39. ·ͱΊ
40. © 2016 KUFU, Inc.  ·ͱΊ •OpenAPI Specification Λར༻͢Δͱ௿ίετ Ͱ͖ͪΜͱͨ͠࢓༷ॻ͕࡞ΕΔ •ϦΫΤετνΣοΫπʔϧͱͯ͠΋࢖͑Δ •಺༰͕௠෗Խ͢ΔϦεΫ΋௿͍ •ར༻͍ͯ͠Δ WAF ʹରԠ͢ΔϥΠϒϥϦ͕͋ Ε͹ಋೖ΋ൺֱత؆୯
41. 0QFO"1*
    4QFDJpDBUJPO
    Ͱ
    εϚʔτʹ
    "1*
    Λӡ༻͠·͠ΐ͏ʂ
42. ΤϯδχΞืूͯ͠·͢
    ࠙਌ձͰ͓࿩͠·͠ΐ͏ʂ
    CFFST w3VCZ
    PO
    3BJMT
    w#
    ޲͚
    4BB4
    wݹͯ͘ڊେͳ੍౓Λ
    )BDL
    ͍ͨ͠
    w4NBSU)3
    "1*
    Λӡ༻͍ͨ͠