Upgrade to Pro — share decks privately, control downloads, hide ads and more …

APIドキュメント標準化現状確認 / standard api document

Avatar for mat mat
June 15, 2016
Technology
0
13k

APIドキュメント標準化現状確認 / standard api document

Excite Japan Co., Ltd.
Lightning Talks
Avatar for mat

mat

June 15, 2016
Tweet

More Decks by mat

See All by mat
Amazon Echoのウェイクワードをカスタマイズする / Customize Amazon Echo Wake Word
Avatar for mat romiogaku
0
450
プリキュアハッカソン4 成果発表 / cure_hack4
Avatar for mat romiogaku
0
910

Other Decks in Technology

See All in Technology
Amazon Bedrockで実現する 新たな学習体験
Avatar for Kazuki Maeda kzkmaeda
2
540
Liquid Glass革新とSwiftUI/UIKit進化
Avatar for Fumiya Sakai fumiyasac0921
0
210
生成AI時代の開発組織・技術・プロセス 〜 ログラスの挑戦と考察 〜
Avatar for Hiroshi Ito itohiro73
0
110
初めてのAzure FunctionsをClaude Codeで作ってみた / My first Azure Functions using Claude Code
Avatar for Hideaki Aoyagi hideakiaoyagi
1
220
生成AIで小説を書くためにプロンプトの制約や原則について学ぶ / prompt-engineering-for-ai-fiction
Avatar for nwiizo nwiizo
4
1.4k
登壇ネタの見つけ方 / How to find talk topics
Avatar for pinkumohikan pinkumohikan
4
390
【５分でわかる】セーフィー エンジニア向け会社紹介
Avatar for Safie safie_recruit
0
26k
_第3回__AIxIoTビジネス共創ラボ紹介資料_20250617.pdf
Avatar for AIxIoTビジネス共創ラボ iotcomjpadmin
0
150
Node-REDのFunctionノードでMCPサーバーの実装を試してみた / Node-RED × MCP 勉強会 vol.1
Avatar for you（@youtoy） you
PRO
0
110
GeminiとNotebookLMによる金融実務の業務革新
Avatar for abenben abenben
0
230
How Community Opened Global Doors
Avatar for hiroramos hiroramos4
PRO
1
120
「Chatwork」の認証基盤の移行とログ活用によるプロダクト改善
Avatar for kubell kubell_hr
1
150

Featured

See All Featured
Site-Speed That Sticks
Avatar for Harry Roberts csswizardry
10
660
ピンチをチャンスに：未来をつくるプロダクトロードマップ #pmconf2020
Avatar for Aki / @LoveIdahoBurger aki_iinuma
124
52k
Cheating the UX When There Is Nothing More to Optimize - PixelPioneers
Avatar for Stéphanie Walter stephaniewalter
281
13k
BBQ
Avatar for Matthew Crist matthewcrist
89
9.7k
The Psychology of Web Performance [Beyond Tellerrand 2023]
Avatar for Tammy Everts tammyeverts
48
2.8k
Typedesign – Prime Four
Avatar for Hannes Fritz hannesfritz
42
2.7k
Bash Introduction
Avatar for André Augusto Costa Santos 62gerente
614
210k
It's Worth the Effort
Avatar for 3n 3n
185
28k
Faster Mobile Websites
Avatar for Dean Hume deanohume
307
31k
The Invisible Side of Design
Avatar for Vitaly Friedman smashingmag
299
51k
Optimising Largest Contentful Paint
Avatar for Harry Roberts csswizardry
37
3.3k
CSS Pre-Processors: Stylus, Less & Sass
Avatar for Bermon Painter bermonpainter
357
30k

Transcript

  1. APIυΩϡϝϯτඪ४Խ ݱঢ়֬ೝ ϝϯόʔγοϓαʔϏεຊ෦ ࿀Ѫ݁ࠗɾ࿀׆ٕज़ηΫγϣϯ দԼ

  2. API࢓༷ॻ͘ͱ͖ Ͳ͏ͯ͠·͔͢ʁ

  3. ԿͰॻ͘ʁ • Markdown • Githubͷwiki • Confluence • excel •

    word

  4. ԿΛॻ͘ʁ • HTTPϝιουʢGET/POST/PUT/DELETE…ʣ • ΤϯυϙΠϯτ • ϦΫΤετύϥϝʔλ • Ϩεϙϯε •

    αϯϓϧ

  5. ߏ଄ͱ஫ऍ

  6. ೔ຊޠ/ӳޠͰॻ͘ʹ͸ ੍໿͕ແ͗͢͞Δ

  7. ࢓༷ॻͷݟ΍͢͞͸ ॻ͖खʹࠨӈ͞ΕΔ

  8. APIυΩϡϝϯτΛ هड़͢Δҝͷ ϧʔϧ/ݴޠ͕ඞཁͩ

  9. APIυΩϡϝϯτΛ هड़͢Δҝͷ ϧʔϧ/ݴޠΛ౷Ұ͠Α͏

  10. http://techslides.com/top-10-free-templates-for-api-documenation

  11. ͍Ζ͍ΖͰ͖ͯͨ

  12. APIυΩϡϝϯτ ࡾॐ࢜Λ࿈Ε͖ͯͨΑ

  13. ࠓͳΒ͜ͷ3͔ͭ • API Blueprint • RAML • Swagger

  14. ͬ͘͟ͱղઆ͠·͢

  15. ྫɿϒϩάهࣄৄࡉऔಘAPI ϦΫΤετ )551ϝιου ΤϯυϙΠϯτ ϦΫΤετ ύϥϝʔλ ϦΫΤετ ϔομ (&5 WBSUJDMF\BSUJDMF@JE^

    BSUJDMF@JE ʢඞਢʣ $POUFOU5ZQFBQQMJDBUJPOKTPO "DDFQUBQQMJDBUJPOKTPO

  16. { "data": { "id": 3, "title": "هࣄλΠτϧ", "body": "<html>HTMLຊจ</html>", "created_at":

    "2016-05-22T14:56:29.000Z", "updated_at": "2016-05-22T14:56:28.000Z", "author": "author1", "tags": [ {"id": 1, "tag_name": "λά໊1"}, {"id": 2, "tag_name": "λά໊2"} ] } } ྫɿϒϩάهࣄऔಘAPI Ϩεϙϯε(200)

  17. API Blueprint

  18. API Blueprint • MarkdownΛ֦ுͨ͠هड़ • JSON Schema΋ཪͰ࡞ͬͯ͘ΕΔ • JSON SchemaɿJSONσʔλߏ଄Λهड़͢Δ

    ͨΊͷॻࣜɾ࢓༷ʢࠓճ͸৮Ε·ͤΜʣ

  19. + Request (application/json) + Headers Accept: application/json + Parameters +

    article_id: 3 (number, required) + Response 200 (application/json) + Attributes + data (required) + id: 3 (number, required) + title: هࣄλΠτϧ (string, required) + body: `<html>HTMLຊจ</html>`(string, required) + created_at: `2016-05-22T14:56:29.000Z` (string, required) + updated_at: `2016-05-22T14:56:28.000Z` (string, required) + author: author1 (string, required) -- هࣄຖʹҰਓͷϢʔβʢஶऀʣ + tags (array) -- هࣄຖʹෳ਺ͷλά + (object) + id: 1 (number, required) + tag_name: λά1 (string, required) + (object) + id: 2 (number, required) + tag_name: λά2 (string, required) blog.apib(Ұ෦ൈਮ)

  20. API Blueprint • Markdownͱݴ͍ͭͭบ͕͋Δ • ҰͭͰ΋ॻ͚͹ίϐϖͰͳΜͱ͔ͳΔ • ϑΝΠϧ෼ׂػೳ͕ͳ͍ͷͰͪ͜ΒͰ݁߹͢ ΔͳΓ͢Δඞཁ͕͋Δ •

    APIυΩϡϝϯτੜ੒πʔϧͷapiary͕༏ल
  21. None
  22. None
  23. None

  24. RAML

  25. RAML • YAMLΛ֦ுͨ͠ه๏ • ڞ௨෦෼Λ࠶ར༻ͨ͠ΓɺଞͷϑΝΠϧ͔Β includeͨ͠ΓͰ͖Δ

  26. schemas: - article: !include sampleblog-include-article.schema resourceTypes: - collection-item: description: Entity

    representing a <<resourcePathName|!singularize>> get: responses: 200: body: application/json: schema: <<resourcePathName|!singularize>> example: | <<exampleItem>> /article: /{article_id}: uriParameters: article_id: description: هࣄID type: integer required: true example: 3 type: collection-item: exampleItem: !include sampleblog-include-article-item.sample description: هࣄ୯ମ get: description: هࣄৄࡉΛऔಘ͢ΔɻهࣄݸผϖʔδͰ࢖༻͠ɺهࣄຖͷauthor,tag৘ใ΋ฦ٫͢Δ blog.raml(Ұ෦)

  27. schemas: - article: !include sampleblog-include-article.schema resourceTypes: - collection-item: description: Entity

    representing a <<resourcePathName|!singularize>> get: responses: 200: body: application/json: schema: <<resourcePathName|!singularize>> example: | <<exampleItem>> /article: /{article_id}: uriParameters: article_id: description: هࣄID type: integer required: true example: 3 type: collection-item: exampleItem: !include sampleblog-include-article-item.sample description: هࣄ୯ମ get: description: هࣄৄࡉΛऔಘ͢ΔɻهࣄݸผϖʔδͰ࢖༻͠ɺهࣄຖͷauthor,tag৘ใ΋ฦ٫͢Δ blog.raml(Ұ෦)

  28. schemas: - article: !include sampleblog-include-article.schema resourceTypes: - collection-item: description: Entity

    representing a <<resourcePathName|!singularize>> get: responses: 200: body: application/json: schema: <<resourcePathName|!singularize>> example: | <<exampleItem>> /article: /{article_id}: uriParameters: article_id: description: هࣄID type: integer required: true example: 3 type: collection-item: exampleItem: !include sampleblog-include-article-item.sample description: هࣄ୯ମ get: description: هࣄৄࡉΛऔಘ͢ΔɻهࣄݸผϖʔδͰ࢖༻͠ɺهࣄຖͷauthor,tag৘ใ΋ฦ٫͢Δ blog.raml(Ұ෦)

  29. RAML • Լखʹܧঝؔ܎͕ఆٛͰ͖Δ͍ͤͰপʹ͸·Γͦ͏ • yamlͰແཧ͠ա͗Ͱ͸ɾɾɾʁ • 0.8ͱ1.0Ͱهड़݁ߏҧ͏ • json schemaͷ࢓༷΋஌͓ͬͯ͘ඞཁ͕͋Δ

    • apiaryʹࣅͨʮAPI Designerʯͱ͍͏αʔϏε͕࢖͑Δ • AtomϓϥάΠϯ(API Workbench)΋͋Γ·͢

  30. Swagger

  31. Swagger • 3ͭͷதͰ͸࠷ݹࢀ • ࢓༷ˠ࣮૷ͷτοϓμ΢ϯɺɹɹɹɹɹɹɹ ࣮૷ˠ࢓༷ͷϘτϜΞοϓͷ྆ํʹରԠ • JSON͔YAMLͰ࢓༷(Swagger Spec)Λॻ͘

  32. swagger: '2.0' host: sampleblog.com basePath: /v1 paths: /article/{article_id}: get: summary:

    هࣄৄࡉ description: | هࣄৄࡉΛऔಘ͢ΔɻهࣄݸผϖʔδͰ࢖༻͠ɺهࣄຖͷauthor,tag৘ใ΋ฦ٫͢Δ parameters: - name: article_id in: path description: هࣄID required: true type: number tags: - Article responses: 200: description: هࣄৄࡉ schema: $ref: '#/definitions/Article' swagger.yaml(Ұ෦)

  33. swagger: '2.0' host: sampleblog.com basePath: /v1 paths: /article/{article_id}: get: summary:

    هࣄৄࡉ description: | هࣄৄࡉΛऔಘ͢ΔɻهࣄݸผϖʔδͰ࢖༻͠ɺهࣄຖͷauthor,tag৘ใ΋ฦ٫͢Δ parameters: - name: article_id in: path description: هࣄID required: true type: number tags: - Article responses: 200: description: هࣄৄࡉ schema: $ref: '#/definitions/Article' swagger.yaml(Ұ෦)

  34. definitions: Article: type: object required: - id - title -

    body - created_at - updated_at - author - tags properties: id: type: number description: هࣄID title: type: string description: هࣄλΠτϧ body: type: string description: HTMLຊจ created_at: type: string format: datetime description: ࡞੒೔࣌ updated_at: type: string format: datetime description: ߋ৽೔࣌ author: type: string swagger.yaml(ଓ͖,Ұ෦ൈਮ)

  35. Swagger • ؔ࿈πʔϧ͕ଟ͘ɺ3ͭͷதͰҰ൪ଟػೳ • ͱ͖ͬͭʹ͘͞No.1 • มʹڽͬͯͳ͍ͷͰ֮͑΍͍͢ʢͱࢥ͏ʣ • ʮSwagger CodegenʯͰαʔόStub/ΫϥΠΞϯτίʔυΛ

    ు͖ग़ͤΔ • BetaͰapiary΋ରԠ͍ͯ͠Δ͕ɺʮSwagger Editorʯ͕࢖͑Δ
  36. None

  37. ͲΕΛ࢖͑͹ɾɾɾ

  38. ௕͍΋ͷʹר͔Ε·͠ΐ͏

  39. GoogleτϨϯυ

  40. Open API Initiative • RESTFul APIͷΠϯλʔϑΣʔεΛهड़͢Δͨ Ίͷඪ४ϑΥʔϚοτΛਪਐ͢Δஂମ • 2015೥ɺLinux FoundationڠྗͷԼ݁੒

    • SwaggerΛ࠾༻

  41. Open API Initiative

  42. Swagger͕উͪͦ͏ʁ

  43. νʔϜ಺Ͱ࢖͍΍͍͢΋ͷΛ ࢖͍·͠ΐ͏

  44. ͓ΘΓ