Q&A for How to use OpenAPI3 for API developer

AFTER RubyKaigi 2019での発表資料です
https://raksul.connpass.com/event/125165/

Transcript

1. Q&A for 

   How to use OpenAPI3
   for API developer
   AFTER RubyKaigi 2019
   ota42y
   

   View Slide

2. about me
   

   View Slide

3. about me
   • @ota42y
   • ϔϧεςοΫΧϯύχʔͷαʔόαΠυΤϯδχΞ
   • ϚΠΫϩαʔϏεΑΖͣຊΈ͍ͨͳͷΛग़ͯ͠·͢
   • ిࢠ൛΋͋ΔΑ(ƅ㱼ƅ)oኯƅ
   • https://ota42y.booth.pm/items/1316740
   • https://ota42y.booth.pm/items/1316130
   

   View Slide

4. Today’s topic
   • OpenAPI3ͷൃදͷ͓͞Β͍
   • دͤΒΕ࣭ͨ໰ͱճ౴
   

   View Slide

5. OpenAPI3ͷൃදͷ͓͞Β͍
   

   View Slide

6. OpenAPI3
   • ϓϩάϥϛϯάݴޠʹґଘ͠ͳ͍REST APIͷͨΊͷఆٛ
   • ͔ͭͯ͸Swaggerͱݺ͹Ε͍ͯͯɺͦΕͷ࣍όʔδϣϯ
   • ϚγʔϯϦʔμϒϧͳYAML/JSONͷϧʔϧͰɺυΩϡϝϯτ
   ੜ੒΍όϦσʔγϣϯɺϞοΫαʔό΍ϥΠϒϥϦੜ੒ͳͲԠ
   ༻͸ଟ਺
   https://www.openapis.org/
   

   View Slide

7. APIͷఆٛͷॏཁੑ
   • େྔʹAPI͕͋Δ৔߹ɺυΩϡϝϯτ͕ॏཁʹͳΔ

   (ϚΠΫϩαʔϏεͩͱ1000ݸҎ্API͕͋ͬͨΓ͢Δ)
   • εΩʔϚϑΝʔετ։ൃ͢Δ৔߹ɺΠϯλϑΣʔεΛ͖ͬͪΓ
   ఆٛ͢Δඞཁ͕͋Δ
   • εΩʔϚϑΝʔετ։ൃʹ͍ͭͯৄ͘͠͸ͬͪ͜
   Reference:
   RubyKaigi 2017 API Development in 2017 https://www.youtube.com/watch?v=a28jJ62ZfZM
   Rails Developers Meetup 2019: 

   https://speakerdeck.com/aeroastro/rails-meets-protocol-buffers-for-schema-first-development
   

   View Slide

8. ਓͷखʹΑΔԹ͔Έͷ͋Δఆٛ͸่ΕΔ
   • ࣮૷ͱఆ͕ٛҰக͍ͯ͠Δͷ͕େલఏ
   • ͣΕΔͱఆ͕ٛ৴པͰ͖ͳ͘ͳΔ
   • ౒ྗͰҰகͤ͞Δͷ͸ແཧ
   

   View Slide

9. OpenAPI 3ʹΑΔࣗಈνΣοΫ
   • OpenAPI 3͸ϚγʔϯϦʔμϒϧͳఆٛ
   • ఆٛͱͷζϨΛϓϩάϥϜͰνΣοΫͰ͖Δ
   • committee
   • rack૚Ͱrequest/response͕ఆٛͲ͓Γ͔ΛνΣοΫ͢Δgem
   • ఆٛ௨Γͷ࣮૷Ͱ͋ΔͱอূͰ͖Δ
   

   View Slide

10. Example API
    get "/apps" do
    content_type :json
    # page should be Integer
    page = params["page"]
    [page, (page*10)].map(&:to_s).to_json
    end
    

    View Slide

11. Example API
    openapi: 3.0.0
    info:
    title: Sample API
    version: 0.1.0
    paths:
    "/apps":
    get:
    parameters:
    - name: page
    in: query
    required: true
    schema:
    type: integer
    responses:
    '200':
    description: example
    content:
    'application/json':
    schema:
    type: array
    items:
    type: string
    

    View Slide

12. Example API
    openapi: 3.0.0
    info:
    title: Sample API
    version: 0.1.0
    paths:
    "/apps":
    get:
    parameters:
    - name: page
    in: query
    required: true
    schema:
    type: integer
    responses:
    '200':
    description: example
    content:
    'application/json':
    schema:
    type: array
    items:
    type: string
    

    View Slide

13. Example API
    openapi: 3.0.0
    info:
    title: Sample API
    version: 0.1.0
    paths:
    "/apps":
    get:
    parameters:
    - name: page
    in: query
    required: true
    schema:
    type: integer
    responses:
    '200':
    description: example
    content:
    'application/json':
    schema:
    type: array
    items:
    type: string
    

    View Slide

14. ͦͷଞͷOpenAPI 3ͷ׆༻
    • OpenAPI Generator
    • client libraryΛੜ੒͢Δπʔϧ
    • Swagger Editor
    • OpenAPI 3ͷఆٛΛॻ͘ΠϯλϥΫςΟϒͳΤσΟλ
    • ࣮ࡍʹαʔόʹϦΫΤετΛ஗ΕΔυΩϡϝϯτΛॻ͚Δ
    • ଞʹ΋Protocol BuffersΛੜ੒ͨ͠Γͱ͔৭ʑ…ৄ͘͠͸ https://openapi.tools/ ΁
    

    View Slide

15. Q&A for 

    How to use OpenAPI 3
    for API developer
    

    View Slide

16. Q.committee͸ຊ൪؀ڥͰ࢖ͬͯΔ͔?
    • Yes
    • committee͸ܕͷύϥϝʔλΛม׵͢Δػೳ͕͋ΔͷͰrequestͰ͸࢖ͬͯΔ

    (datetimeͳstringΛDateTimeΫϥεʹͨ͠ΓɺGETͩͱ͢΂ͯstringʹͳΔͷ
    ͰIntegerʹ͢Δͱ͔)
    • ϦΫΤετʹ͔͠దԠ͞Εͳ͍ͨΊɺϨεϙϯεͷόϦσʔγϣϯ͸ͯ͠ͳ͍
    • ։ൃ؀ڥʹ͓͍ͯ͸requset/responseͷόϦσʔγϣϯΛೖΕ͍ͯΔ
    

    View Slide

17. Q.committee ΛೖΕͨ͜ͱʹΑΔӨڹ͸?
    • ϕϯνϚʔΫΛऔΓ·ͨ͠
    • https://gist.github.com/ota42y/1a5fb27e31aa5868af307fd66f52878b
    • ύϥϝʔλ͕1ݸͷখن໛
    • ύϥϝʔλ͕260ݸͷதن໛
    • ύϥϝʔλ͕2600ݸͷେن໛
    • ͦΕͧΕcommitteeͷON/OFFͰ10000ճܭଌ
    

    View Slide

18. committee ΛೖΕͨ͜ͱʹΑΔӨڹ͸?
    • responseʹؔͯ͠͸νΣοΫͯ͠ͳ͍
    • ࣮૷ͱͯ͠͸ڞ௨ͳͷͰ΄΅มΘΒͳ͍͸ͣ
    • ؀ڥ͸Ruby 2.6.3ɺMac Book Pro, Core i5 2.7GHz
    

    View Slide

19. ίʔυ
    • https://gist.github.com/ota42y/
    1a5fb27e31aa5868af307fd66f52878b
    

    View Slide

20. VTFS TZTUFN UPUBM SFBM
    /PU6TF
    6TF
    খن໛
    • 10000 times request time so 0.08 ms per request
    • So the committee doesn’t take 0.1 millisecond
    • The difference is very small
    

    View Slide

21. தن໛
    • Validate 260 objects by 0.16 milliseconds per request
    • But the difference is still small
    VTFS TZTUFN UPUBM SFBM
    /PU6TF
    6TF
    

    View Slide

22. େن໛
    • Validate 2600 objects by 0.74 milliseconds per request
    • It’s very small difference
    VTFS TZTUFN UPUBM SFBM
    /PU6TF
    6TF
    

    View Slide

23. A.ϕϯνϚʔΫ݁Ռ
    • தن໛ύϥϝʔλͰ΋େ͖ࠩ͘͸ग़ͯͳ͍
    • Mac Book Pro؀ڥͰ0.1ʙ2ms
    • Կ΋ແ͍࣌ͱͷࠩ͸খ͍͞
    • ࣮ࡍͷαʔόͰ΋΄΅Өڹ͸ແ͍͸ͣ
    • requestʹ100ύϥϝʔλ৐Δͷ͸͔ͳΓେ͖͍͜ͱΛߟ͑Δͱɺ΄΅ແࢹ
    Ͱ͖Δ͸ͣ
    

    View Slide

24. Q. OpenAPI 3.0.1ͩͱಈ͔ͳ͍Μ͚ͩͲ
    • ͖ͬ͞௚͠·ͨ͠
    

    View Slide

25. Q. OpenAPI 3.0.1ͩͱಈ͔ͳ͍Μ͚ͩͲ
    • ϦϦʔε΋ͯ͋͠Γ·͢㱬(ɾ8ɾ)⊃
    

    View Slide

26. ຊ൪͸͜͜Ͱ࣌ؒ੾Ε
    

    View Slide

27. Q.GraphQL / gRPC ͱൺ΂ͯͲ͏Α
    • ͲΕ͕͍͍͔͸ϝϯόʔ΍ΫϥΠΞϯτଆͷ࣮૷ɺݴޠʹΑΔ
    • GraphQL͸ಋೖ͚ͯͨ͠ͲΞϓϦଆͷ࣮૷ઓུʹ߹Θͣʹ׆༻Ͱ͖ͣɺ݁
    ہࣺͯͨ
    • gRPC͸Railsͩͱݱঢ়·ͩਏ͍ͱ͍͏ࣄ࣮
    • Go ͱ͔ͳΒ༗ྗͳબ୒ࢶ
    • ΫοΫύου͕ؤுͬͯΔ
    

    View Slide

28. ࠓͷੈք͸RESTʹ࠷దԽ͞ΕͯΔ
    • ΤίγεςϜͱ͔஌ݟ͸REST͕ੌ͍
    • ͦ΋ͦ΋Rails͸RESTͱ਌࿨ੑ͕͍͍
    • GraphQL/gRPCΛೖΕΔͷ͸͍ͩͿΤωϧΪʔ͕ඞཁ
    • ಉ͡࿑ྗΛRESTͱGraphQL/gRPCͷͲΕʹׂ͘ͷ͕Ұ൪͔
    • ͔ͳΓޮՌతͳ৔໘΋͋ΔͷͰɺݟۃΊͱ֮ޛ
    

    View Slide