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

Excite Japan Co., Ltd.
Lightning Talks

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͕༏ल
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ʯ͕࢖͑Δ
37. ͲΕΛ࢖͑͹ɾɾɾ
38. ௕͍΋ͷʹר͔Ε·͠ΐ͏
39. GoogleτϨϯυ
40. Open API Initiative • RESTFul APIͷΠϯλʔϑΣʔεΛهड़͢Δͨ Ίͷඪ४ϑΥʔϚοτΛਪਐ͢Δஂମ • 2015೥ɺLinux FoundationڠྗͷԼ݁੒ • SwaggerΛ࠾༻
41. Open API Initiative
42. Swagger͕উͪͦ͏ʁ
43. νʔϜ಺Ͱ࢖͍΍͍͢΋ͷΛ ࢖͍·͠ΐ͏
44. ͓ΘΓ