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

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

API࢓༷ॻ͘ͱ͖ Ͳ͏ͯ͠·͔͢ʁ

ԿͰॻ͘ʁ • Markdown • Githubͷwiki • Conﬂuence • excel •
word

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

ߏ଄ͱ஫ऍ

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

࢓༷ॻͷݟ΍͢͞͸ ॻ͖खʹࠨӈ͞ΕΔ

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

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

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

͍Ζ͍ΖͰ͖ͯͨ

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

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

ͬ͘͟ͱղઆ͠·͢

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

{ "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)

API Blueprint

API Blueprint • MarkdownΛ֦ுͨ͠هड़ • JSON Schema΋ཪͰ࡞ͬͯ͘ΕΔ • JSON SchemaɿJSONσʔλߏ଄Λهड़͢Δ
ͨΊͷॻࣜɾ࢓༷ʢࠓճ͸৮Ε·ͤΜʣ

+ 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(Ұ෦ൈਮ)

API Blueprint • Markdownͱݴ͍ͭͭบ͕͋Δ • ҰͭͰ΋ॻ͚͹ίϐϖͰͳΜͱ͔ͳΔ • ϑΝΠϧ෼ׂػೳ͕ͳ͍ͷͰͪ͜ΒͰ݁߹͢ ΔͳΓ͢Δඞཁ͕͋Δ •
APIυΩϡϝϯτੜ੒πʔϧͷapiary͕༏ल

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

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(Ұ෦)

RAML • Լखʹܧঝؔ܎͕ఆٛͰ͖Δ͍ͤͰপʹ͸·Γͦ͏ • yamlͰແཧ͠ա͗Ͱ͸ɾɾɾʁ • 0.8ͱ1.0Ͱهड़݁ߏҧ͏ • json schemaͷ࢓༷΋஌͓ͬͯ͘ඞཁ͕͋Δ
• apiaryʹࣅͨʮAPI Designerʯͱ͍͏αʔϏε͕࢖͑Δ • AtomϓϥάΠϯ(API Workbench)΋͋Γ·͢

Swagger

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

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(Ұ෦)

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(ଓ͖,Ұ෦ൈਮ)

Swagger • ؔ࿈πʔϧ͕ଟ͘ɺ3ͭͷதͰҰ൪ଟػೳ • ͱ͖ͬͭʹ͘͞No.1 • มʹڽͬͯͳ͍ͷͰ֮͑΍͍͢ʢͱࢥ͏ʣ • ʮSwagger CodegenʯͰαʔόStub/ΫϥΠΞϯτίʔυΛ
ు͖ग़ͤΔ • BetaͰapiary΋ରԠ͍ͯ͠Δ͕ɺʮSwagger Editorʯ͕࢖͑Δ

ͲΕΛ࢖͑͹ɾɾɾ

௕͍΋ͷʹר͔Ε·͠ΐ͏

GoogleτϨϯυ

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

Open API Initiative

Swagger͕উͪͦ͏ʁ

νʔϜ಺Ͱ࢖͍΍͍͢΋ͷΛ ࢖͍·͠ΐ͏

͓ΘΓ

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

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

More Decks by mat

Other Decks in Technology

Featured

Transcript