Sometime, real API and documentation have deep groove. So I have decided to create document from real API request and response. At first, I have created swagger from API response. After that, I have published mkdocs documents from swagger.

1. PAGEDAY2017/11/01#MOONGIFT/12
How to create the API document
from real API and localization
1

2. PAGEDAY2017/11/01#MOONGIFT/12
Who am I?
2
@goofmint
fb.me/goofmint
Atsushi Nakatsugawa
CEO at MOONGIFT
Organizer of DevRelCon Tokyo 2017/2018
Organizer of DevRel Meetup in Tokyo/Singapore/Sydney/Bangalore

3. PAGEDAY2017/11/01#MOONGIFT/12
! Give me your feedback! !
3
API THE DOCS, 9 November London

4. PAGEDAY2017/11/01#MOONGIFT/12
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
4

5. PAGEDAY2017/11/01#MOONGIFT/12
First Situation
5

6. PAGEDAY2017/11/01#MOONGIFT/12
First situation
• API document is managed by GitHub Wiki
• Minimum quality, for their workers
• Ineffective maintenance document
6

7. PAGEDAY2017/11/01#MOONGIFT/12
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.
7

8. PAGEDAY2017/11/01#MOONGIFT/12
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.
8
I've decided creating document from zero.

9. PAGEDAY2017/11/01#MOONGIFT/12
Specifications
9

10. PAGEDAY2017/11/01#MOONGIFT/12
Specifications
• Support English and Japanese
• Document has API, tutorials, usage and more
• Easy maintenance
10

11. PAGEDAY2017/11/01#MOONGIFT/12
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)
11

12. PAGEDAY2017/11/01#MOONGIFT/12
Translating is not localization
• Structure of sentence is completely different
• Many times, English needs longer sentence than Japanese
• Japanese has 3 types characters (Hiragana/Katakana/Kanji)
12

13. PAGEDAY2017/11/01#MOONGIFT/12
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

14. PAGEDAY2017/11/01#MOONGIFT/12
Architecture
14
API
Swagger
OAS
GetText
Markdown
Static Site
Generator

15. PAGEDAY2017/11/01#MOONGIFT/12
Works
15

16. PAGEDAY2017/11/01#MOONGIFT/12
Architecture
16
API
Swagger
OAS
GetText
Markdown
Static Site
Generator

17. PAGEDAY2017/11/01#MOONGIFT/12
Real API to Swagger
• There is kitchen sink app
• Developer can learn how to use JavaScript SDK & API
17

18. PAGEDAY2017/11/01#MOONGIFT/12
Tool 1 : curlToSwagger
• Chrome provides curl command in Devtools
• Copy it
• Parse it
• Generate swagger document
18
https://github.com/goofmint/cURLtoSwagger

19. PAGEDAY2017/11/01#MOONGIFT/12
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'

20. PAGEDAY2017/11/01#MOONGIFT/12
Tool 1 : curlToSwagger
• Chrome provides curl command in Devtools
• Copy it
• Parse it
• Generate swagger document
20
https://github.com/goofmint/cURLtoSwagger

21. PAGEDAY2017/11/01#MOONGIFT/12
Tool 1 : curlToSwagger
• Chrome provides curl command in Devtools
• Copy it
• Parse it
• Generate swagger document
21
https://github.com/goofmint/cURLtoSwagger

22. PAGEDAY2017/11/01#MOONGIFT/12
Architecture
22
API
Swagger
OAS
GetText
Markdown
Static Site
Generator

23. PAGEDAY2017/11/01#MOONGIFT/12
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
23
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"

24. PAGEDAY2017/11/01#MOONGIFT/12
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 "バイブレーション 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 "メソッド"

25. PAGEDAY2017/11/01#MOONGIFT/12
Architecture
25
API
Swagger
OAS
GetText
Markdown
Static Site
Generator

26. PAGEDAY2017/11/01#MOONGIFT/12
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.
26
https://www.mkdocs.org

27. PAGEDAY2017/11/01#MOONGIFT/12
Conclusion
27

28. PAGEDAY2017/11/01#MOONGIFT/12
API to Document
• Document is not code
• Too many comments lower readability of code
• Test code or kitchen sink is good tutorial for programmers
• 1 correct code is more worth than 100 words
28

29. PAGEDAY2017/11/01#MOONGIFT/12
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
29

30. PAGEDAY2017/11/01#MOONGIFT/12
Thanks! $
30