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

E1dbe585427fa87cbfb0f4dbcebc3b2f?s=47 mizuki_r
September 02, 2016

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

2016-09-02 Gotanda.js #5 の発表資料

E1dbe585427fa87cbfb0f4dbcebc3b2f?s=128

mizuki_r

September 02, 2016
Tweet

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. モックの例 (&5BQJVTFSVTFS@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. (SPVQ6TFS (&5BQJVTFS\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. ご清聴ありがとうございまし た