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
630
GolangでAPIドキュメント自動生成
社内LT
Masaki Iino
November 17, 2017
Tweet
Share
More Decks by Masaki Iino
See All by Masaki Iino
GCP Composer
iinomasaki
0
230
AnyPay ChatOps
iinomasaki
0
1.2k
Istio
iinomasaki
0
1.6k
LT_Cloud_Functions.pdf
iinomasaki
1
550
Other Decks in Technology
See All in Technology
ExaDB-D dbaascli で出来ること
oracle4engineer
PRO
0
3.6k
ABEMA のコンテンツ制作を最適化!生成 AI x クラウド映像編集システム / abema-ai-editor
cyberagentdevelopers
PRO
1
180
pandasはPolarsに性能面で追いつき追い越せるのか
vaaaaanquish
4
4.6k
生成AIと知識グラフの相互利用に基づく文書解析
koujikozaki
1
140
いまならこう作りたい AWSコンテナ[本格]入門ハンズオン 〜2024年版 ハンズオンの構想〜
horsewin
9
2.1k
Jr. Championsになって、強く連携しながらAWSをもっと使いたい!~AWSに対する期待と行動~
amixedcolor
0
190
ネット広告に未来はあるか?「3rd Party Cookie廃止とPrivacy Sandboxの効果検証の裏側」 / third-party-cookie-privacy
cyberagentdevelopers
PRO
1
130
初心者に Vue.js を 教えるには
tsukuha
5
390
Gradle: The Build System That Loves To Hate You
aurimas
2
150
CAMERA-Suite: 広告文生成のための評価スイート / ai-camera-suite
cyberagentdevelopers
PRO
3
270
分布で見る効果検証入門 / ai-distributional-effect
cyberagentdevelopers
PRO
4
700
新卒1年目が向き合う生成AI事業の開発を加速させる技術選定 / ai-web-launcher
cyberagentdevelopers
PRO
7
1.5k
Featured
See All Featured
Stop Working from a Prison Cell
hatefulcrawdad
267
20k
Git: the NoSQL Database
bkeepers
PRO
425
64k
Designing on Purpose - Digital PM Summit 2013
jponch
115
6.9k
Typedesign – Prime Four
hannesfritz
39
2.4k
Measuring & Analyzing Core Web Vitals
bluesmoon
1
40
Teambox: Starting and Learning
jrom
132
8.7k
How to Ace a Technical Interview
jacobian
275
23k
RailsConf 2023
tenderlove
29
880
Automating Front-end Workflow
addyosmani
1365
200k
Put a Button on it: Removing Barriers to Going Fast.
kastner
59
3.5k
Building Applications with DynamoDB
mza
90
6.1k
Agile that works and the tools we love
rasmusluckow
327
21k
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 でタイポも防げる • 楽できる