How to Create the API Document from Real API and Localization
0 likes167 views
The document discusses the challenges of maintaining API documentation and emphasizes the need for a structured approach that supports localization for English and Japanese. It introduces tools like curltoswagger and swagger2markdown to facilitate the generation and maintenance of API documentation. The conclusion highlights the importance of creating user-friendly, localized documentation while acknowledging the difficulties in keeping it updated.
![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](https://image.slidesharecdn.com/howtocreatetheapidocumentfromrealapiandlocalization1-191112155409/85/How-to-Create-the-API-Document-from-Real-API-and-Localization-13-320.jpg)
How to Create the API Document from Real API and Localization
- 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
- 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.
- 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
- 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
- 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