Slide 1
Slide 1 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
How to create the API document
from real API and localization
1
Slide 2
Slide 2 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Who am I?
2
@goofmint
fb.me/goofmint
Atsushi Nakatsugawa
CEO at MOONGIFT
Evangelist
Community
Organizer
Slide 3
Slide 3 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
About this talk
• It is based on my experience
• I will share with you how to improving document
maintenance environment
• It’s not high level and no smart, but it’s realistic
3
Slide 4
Slide 4 text
PAGE
DAY 2018/11/09
# MOONGIFT / 29
First Situation
4
Slide 5
Slide 5 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
First situation
• API document is managed by GitHub Wiki
• Minimum quality, for their workers
• Ineffective maintenance document
5
Slide 6
Slide 6 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
GitHub Wiki
• Updating content on web browser and supporting version management.
• Dividing code and document. Don’t support pull request workflow.
• Don’t support localization.
6
Slide 7
Slide 7 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Un documentation API
• Wiki didn’t cover everything and every update.
• Checking is very hard job that what is collect or not.
• Halfway document disturbs my job.
7
I've decided creating document from zero.
Slide 8
Slide 8 text
PAGE
DAY 2018/11/09
# MOONGIFT / 29
Specifications
8
Slide 9
Slide 9 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Specifications
• Support # and $
• Document has API, tutorials, usage and more
• Easy maintenance
9
Slide 10
Slide 10 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Localization
• Make misunderstanding by no native language
• English speaking rate is too low in Japan (12%)
• Update document cost is very high (English to Japanese)
10
Slide 11
Slide 11 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Translating is not
localization
• Structure of sentence is completely different
• Many times, English needs longer sentence than Japanese
• Machine translation is weird
11
Slide 12
Slide 12 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Translating is not
localization
• Structure of sentence is completely different
• Many times, English needs longer sentence than Japanese
• Machine translation is weird
12
Slide 13
Slide 13 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Document in Code
• Connecting code and document
• Too much comment in code for
documentation
• Programmer is NOT necessarily able
to write high readability document
• Most document generators don’t
support i18n.
13
desc 'Returns your public timeline.' do
summary 'summary'
detail 'more details'
params API::Entities::Status.documentation
success API::Entities::Entity
failure [[401, 'Unauthorized', 'Entities::Error']]
named 'My named route'
headers XAuthToken: {
description: 'Validates your identity',
required: true
},
XOptionalHeader: {
description: 'Not really needed',
required: false
}
hidden false
deprecated false
is_array true
nickname 'nickname'
produces ['application/json']
consumes ['application/json']
tags ['tag1', 'tag2']
end
get :public_timeline do
Status.limit(20)
end
Slide 14
Slide 14 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Architecture
14
API Swagger GetText
Markdown
Static Site
Generator
Slide 15
Slide 15 text
PAGE
DAY 2018/11/09
# MOONGIFT / 29
Works
15
Slide 16
Slide 16 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Architecture
16
API Swagger GetText
Markdown
Static Site
Generator
Slide 17
Slide 17 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Real API to Swagger
• There is kitchen sink app
• Developer can learn how to use JavaScript SDK & API
17
Slide 18
Slide 18 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Tool 1 : curlToSwagger
• Chrome provides curl command in Devtools
• Copy it
• Parse it
• Generate swagger document
18
https://github.com/goofmint/cURLtoSwagger
Slide 19
Slide 19 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Tool 1 : curlToSwagger
• Chrome provides curl command in Devtools
• Copy it
• Parse it
• Generate swagger document
19
https://github.com/goofmint/cURLtoSwagger
curl ‘https://samples.openweathermap.org/data/2.5/forecast?
id=52...a1' \
-XGET \
-H 'Cookie: __utma=124); __utmt=1' \
-H 'Accept: text...q=0.8’ \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Upgrade-Insecure-Requests: 1' \
-H 'Host: samples.openweathermap.org' \
-H 'User-Agent: Mozilla...15’ \
-H 'Accept-Language: ja-jp' \
-H 'DNT: 1' \
-H 'Connection: keep-alive'
Slide 20
Slide 20 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Tool 1 : curlToSwagger
• Chrome provides curl command in Devtools
• Copy it
• Parse it
• Generate swagger document
20
https://github.com/goofmint/cURLtoSwagger
Slide 21
Slide 21 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Tool 1 : curlToSwagger
• Chrome provides curl command in Devtools
• Copy it
• Parse it
• Generate swagger document
21
https://github.com/goofmint/cURLtoSwagger
Slide 22
Slide 22 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Tool 1 : curlToSwagger
• Chrome provides curl command in Devtools
• Copy it
• Parse it
• Generate swagger document
22
https://github.com/goofmint/cURLtoSwagger
Slide 23
Slide 23 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Architecture
23
API Swagger GetText
Markdown
Static Site
Generator
Slide 24
Slide 24 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Tool 2 : Swagger2Markdown
• Parse swagger file
• Pick up each sentences
• Make po file for translating (ja.po or en.po)
• Update po file
• Create English and Japanese Markdown files
24
https://github.com/goofmint/swagger2markdown
# vibration.md
msgid "Vibration API"
msgstr "Vibration API"
# vibration.md
msgid "### Basic specifications"
msgstr "### Basic specifications"
# vibration.md
msgid "API Path"
msgstr "API Path"
# vibration.md
msgid ": /gotapi/vibration/vibrate"
msgstr ": /gotapi/vibration/vibrate"
# vibration.md
msgid "Method"
msgstr "Method"
Slide 25
Slide 25 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Tool 2 : Swagger2Markdown
• Parse swagger file
• Pick up each sentences
• Make po file for translating (ja.po or en.po)
• Update po file
• Create English and Japanese Markdown files
25
https://github.com/goofmint/swagger2markdown
# vibration.md
msgid "Vibration API"
msgstr "όΠϒϨʔγϣϯ API"
# vibration.md
msgid "### Basic specifications"
msgstr "### جຊ༷"
# vibration.md
msgid "API Path"
msgstr "APIύε"
# vibration.md
msgid ": /gotapi/vibration/vibrate"
msgstr ": /gotapi/vibration/vibrate"
# vibration.md
msgid "Method"
msgstr "ϝιου"
Slide 26
Slide 26 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Example
26
,FZ &OHMJTI +BQBOFTF
BQJJUFNTOBNF *UFN"1* "1*
BQJJUFNTTVNNBSZ 3FUVSOJUFNT:PVDBOTFBSDIJUFNTXJUIRVFSZ
Λऔಘ͠·͢ɻݕࡧ݅ΛࢦఆͰ͖·
͢ɻ
BQJJUFNTDPVOUPOF \DPVOU^JUFN \DPVOU^ݸ
BQJJUFNTDPVOUNPSF \DPVOU^JUFNT \DPVOU^ݸ
Slide 27
Slide 27 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Architecture
27
API Swagger GetText
Markdown
Static Site
Generator
Slide 28
Slide 28 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Why Markdown?
• Most swagger based document generators
don’t support localization.
• Many static site generators support
Markdown format
• We can add more contents like tutorials,
getting started, SDK help and more!
• We choose MkDocs for documentation.
28
https://www.mkdocs.org
Slide 29
Slide 29 text
PAGE
DAY 2018/11/09
# MOONGIFT / 29
Conclusion
29
Slide 30
Slide 30 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
API to Document
• Document is not code
• Too many comments are lower readability of code
• Test code or kitchen sink is good tutorial for programmers
• 1 correct code is more worth than 100 words
30
Slide 31
Slide 31 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Localization
• It’s very important for non-native English speakers
• It’s easy to create just one time
• It’s difficult to update document immediately
31
Slide 32
Slide 32 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
We are NOT hiring
• We want your CFP of DevRelCon Tokyo 2019
• Meet at Tokyo on March 9th
• Follow @DevRelConTokyo
32
Slide 33
Slide 33 text
PAGE
# MOONGIFT / 29
DAY 2018/11/09
Thanks! &
33
@goofmint
fb.me/goofmint