Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
GolangでAPIドキュメント自動生成
Search
Masaki Iino
November 17, 2017
Technology
0
710
GolangでAPIドキュメント自動生成
社内LT
Masaki Iino
November 17, 2017
Tweet
Share
More Decks by Masaki Iino
See All by Masaki Iino
GCP Composer
iinomasaki
0
240
AnyPay ChatOps
iinomasaki
0
1.2k
Istio
iinomasaki
0
1.6k
LT_Cloud_Functions.pdf
iinomasaki
1
570
Other Decks in Technology
See All in Technology
ゴリラ.vim #36 ~ Vim x SNS ~ スポンサーセッション
yasunori0418
1
360
Introduction to Bill One Development Engineer
sansan33
PRO
0
240
GitHub Coding Agent 概要
kkamegawa
1
1.8k
Introduction to Sansan for Engineers / エンジニア向け会社紹介
sansan33
PRO
5
38k
【5分でわかる】セーフィー エンジニア向け会社紹介
safie_recruit
0
25k
Oracle Base Database Service 技術詳細
oracle4engineer
PRO
8
65k
人とAIとの共創を夢見た2か月 #共創AIミートアップ / Co-Creation with Keito-chan
kondoyuko
1
720
オープンソースのハードウェアのコンテストに参加している話
iotengineer22
0
690
実践Kafka Streams 〜イベント駆動型アーキテクチャを添えて〜
joker1007
1
610
エンジニアが組織に馴染むために勉強会を主催してチームの壁を越える
ohmori_yusuke
2
120
大規模PaaSにおける監視基盤の構築と効率化の道のり
lycorptech_jp
PRO
0
180
libsyncrpcってなに?
uhyo
0
160
Featured
See All Featured
Product Roadmaps are Hard
iamctodd
PRO
53
11k
Understanding Cognitive Biases in Performance Measurement
bluesmoon
29
1.7k
Speed Design
sergeychernyshev
30
970
Rebuilding a faster, lazier Slack
samanthasiow
81
9k
Fontdeck: Realign not Redesign
paulrobertlloyd
84
5.5k
Why You Should Never Use an ORM
jnunemaker
PRO
56
9.4k
Git: the NoSQL Database
bkeepers
PRO
430
65k
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
32
2.3k
Scaling GitHub
holman
459
140k
Optimising Largest Contentful Paint
csswizardry
37
3.3k
A Modern Web Designer's Workflow
chriscoyier
693
190k
Optimizing for Happiness
mojombo
378
70k
Transcript
GolangでAPIドキュメント自動 生成 2017/11/17 飯野 雅希
APIドキュメント書いてますか?
APIドキュメントは書くのが大変 • Host • Path • HTTPメソッド • Request Header,
Body • Query Parameter • Response Status Code • Response Header, Body • etc...
書き手と読み手が違う • 書くのはサーバーエンジニア • 読むのはフロント・クライアントエンジニア
APIドキュメンテーションツール • Swagger • apiblueprint
API Blueprint • Markdownを使って定義を書く ◦ 拡張子は.apib • Markdownそのままでも読みやすい
API Blueprint • 基本情報 ◦ タイトル ◦ ホスト • グループ
• endopoint情報 ◦ HTTPメソッド ◦ endpoint ◦ リクエスト ◦ パラメータ ◦ レスポンス
読みやすく高機能
だけど、手書きで管理し続けるのは大変
ドキュメントを自動生成しよう 要件 • Golangでコード書いたらapiblueprintでドキュメント自動生成 • apibファイルだとviewerがいるので、HTMLに変換
apiblueprint生成 test2doc:https://github.com/adams-sarah/test2doc • GolangのPackage • Star 236 • Unitテストと組み合わせると自動でAPIドキュメントを生成してくれる
test2doc
test2doc
HTMLに変換 Gulpスクリプトで変換 https://storage.googleapis.com/iino-test-api-doc-test/out.html
所感 • 自動で生成されるのでコードとドキュメントの乖離がなくなる • Go lint/vet でタイポも防げる • 楽できる