APIドキュメントにまつわる試行錯誤 #gotandajs

Transcript

1. APIドキュメントにまつわる 試行錯誤 2016/09/02 Gotanda.JS #5 @mizuki_r

2. @mizuki_r (株)モバイルファクトリー フロントエンドエンジニア JS, Perl Angular, Vue, Riot “HTMLは情報設計言語です！” 2

3. 本日のお題 3

4. APIドキュメントにまつわる 試行錯誤

5. ――を妄想している、 という話をします。

6. 背景

7. 最近の開発スタイル ʘUIϑΝʔετʗ ཁ݅ UI API ϞοΫ API αʔ ό ʔ

   ·ͣ͸UI ৘ใΛ੔ཧ͠ αʔόΛ ࡞Γ UIʹ൓ө͢Δ

8. 最近の開発スタイル • ϑϩϯτerͰAPIϞοΫΛ࡞Δ • αʔόer͸ϞοΫΛݩʹAPIΛ࡞Δ ʘAPIϞοΫͱ͍͏ίϛϡχέʔγϣϯπʔϧʗ

9. ユーザに対して どういう価値を提供するか？ を土台に作れる！ (๑•̀Ŷ•́๑)✧

10. 悩み

11. モックの例 
    (&5
    BQJVTFSVTFS@OBNF
    
    ݸਓ৘ใΛͱͬͯ͘Δ
    \
    
    
    OBNF
    ʠVTFS@OBNFʡ
    
    
    BHF
    
    ^
    ʘJSON5ʗ

12. よくあること • APIϞοΫͱαʔόͷϨεϙϯε͕ζϨΔ • POSTͷϦΫΤετύϥϝʔλ͕Θ͔Βͳ͍ • Ωʔ͕ԿΛ͍ࣔͯ͠Δͷ͔Θ͔Βͳ͍ • ফ͑ͨ͸ͣͷ࢓༷͕ίϝϯτʹ࢒͍ͬͯΔ ʘυΩϡϝϯςʔγϣϯෆ଍ʂʗ

13. 問題… • ࡞੒ऀʹ࢓༷Λ֬ೝ͢Δ • ίʔυΛಡΉ • ࣏͢… ʘ͜ɺίϛϡχέʔγϣϯπʔϧʂʗ

14. ツールで解決

15. API-Blueprint • MarkdownϕʔεͰυΩϡϝϯτΛهड़Ͱ͖ Δ • ύʔαʔΛఏڙ͠ɺ༷ʑͳ֦ு͕͋Δ

16. API-Blueprint • https://apiblueprint.org/ • MarkdownϕʔεͰυΩϡϝϯτΛهड़Ͱ͖ Δ • ύʔαʔΛఏڙ͠ɺ༷ʑͳ֦ு͕͋Δ

17. API-Blueprint

18. with Tools • aglio - HTMLʹυΩϡϝϯτΛ੔ܗ͢Δ • hariko - ϞοΫαʔόΛ্ཱͪ͛Δ

19. with Tools ཁ݅ UI API Blueprint API αʔ ό ʔ

    UIΛઃܭ ৘ใΛ੔ཧ αʔόͷߏங UIʹ൓ө API υΩϡϝϯτ API ϞοΫ ࣗಈੜ੒

20. 解決できそう • ࢓༷Λ໌จԽͰ͖Δ • ॻ͍ͨ΋ͷ͕ͦͷ··ಈ࡞͢Δ • ٙ໰͕͋ͬͨΒ௥ه͢Ε͹͍͍ʂ ʘίϛϡχέʔγϣϯπʔϧʂʗ

21. でも…

22. 問題は残る… • αʔόͱϞοΫͷ࣮૷ࠩ෼ • API-Blueprintͷ๲େͳ࢓༷ • ֶशίετɺϝϯςίετ ʘӡ༻͕ΊΜͲͦ͘͞͏ʗ

23. 妄想 • ΋͏Ұ੠ཉ͍͠ • αʔόͱͷ࣮૷ࠩ෼Λิ׬Ͱ͖Δ • ֶशίετʹݟ߹͏ޮ཰Խ͕Ͱ͖Δ

24. あっ (ﾟ∀ﾟ)!

25. API-Blueprintのデータで Controllerくらいなら 作れんじゃね？ (ﾟ∀ﾟ)!!

26. 人類はどこまで 自動化できるのか〜？

27. API-Blueprintから取れるもの • ز͔ͭͷσʔλͷωετߏ଄ • category, resource, action,transaction,httpTransaction,httpRequest,ht tpResponse,etc…

28. Controllerが要求するもの • ϦΫΤετͷ൑அ • Method, URL, Parameters • ॲཧͷ൑அ •

    Modelͱ͔Serviceͷ໊લۭؒ • Ϩεϙϯεߏ଄ • HttpStatus, Body, Header

29. use Amon2::Lite; use JSON::Types; get '/api/user/:user_name' => sub { my

    ($c, $args) = @_; my $params = $c->req->parametes; my %args = map { $_ => $params->{$_} or $args->{$_} } qw(user_name); my $entity = $c->factory('User')->get(%args); return $c->render_json(+{ name => string($entity->name), age => number($entity->age), }); }; __PACKAGE__->to_app;

30. 
    (SPVQ
    6TFS
    
    (&5
    BQJVTFS\VTFS@OBNF^
    1BSBNFUFST
    VTFS@OBNF
    TUSJOH
    ʜ
    Ϣʔβͷࣝผࢠ
    3FTQPOTF
    
    BQQMJDBUJPOKTPO
    #PEZ
    

    OBNF
    TUSJOH
    
    Ϣʔβͷࣝผࢠ
    BHF
    OVNCFS
    
    ೥ྸ
    #PEZ
    \
    OBNF
    ʠNJ[VLJʡ
    BHF
    
    ^

31. ͳΜ͔ɺ
    Πέͦ͏ͳؾ͕͢Δʜ

32. DEMO https://gist.github.com/rymizuki/ab99a288dfafa841983182eddc0408c9

33. まとめ

34. まとめ • API-Blueprint with aglio x hariko x ??? •

    API-BlueprintΛ༻͍ͨίʔυͷࣗಈੜ੒

35. 所感 • υΩϡϝϯτͱϞοΫͱίʔυ͕࿈ಈ • ཧ࿦্࠷ڧ • ΍Ζ͏ͱࢥ͑͹ߦ͚Δ • Ͱ΋ͦͷ೤ྔʹνʔϜ͸͍ͭͯ͜ΕΔ͔…? •

    ߟྀ͢Δ͜ͱ͕૊߹ͤരൃͯ͠ࢮʹͦ͏…

36. やるなら 有効そう な無茶をしましょう！

37. ご清聴ありがとうございまし た