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
720
GolangでAPIドキュメント自動生成
社内LT
Masaki Iino
November 17, 2017
Tweet
Share
More Decks by Masaki Iino
See All by Masaki Iino
GCP Composer
iinomasaki
0
250
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
AWS環境のリソース調査を Claude Code で効率化 / aws investigate with cc devio2025
masahirokawahara
2
1.3k
kubellが考える戦略と実行を繋ぐ活用ファーストのデータ分析基盤
kubell_hr
0
140
Autonomous Database - Dedicated 技術詳細 / adb-d_technical_detail_jp
oracle4engineer
PRO
4
9.9k
「何となくテストする」を卒業するためにプロダクトが動く仕組みを理解しよう
kawabeaver
0
170
大「個人開発サービス」時代に僕たちはどう生きるか
sotarok
19
9k
Flutterでキャッチしないエラーはどこに行く
taiju59
0
220
ここ一年のCCoEとしてのAWSコスト最適化を振り返る / CCoE AWS Cost Optimization devio2025
masahirokawahara
1
1.5k
ガチな登山用デバイスからこんにちは
halka
1
210
LLM翻訳ツールの開発と海外のお客様対応等への社内導入事例
gree_tech
PRO
0
540
BPaaSにおける人と協働する前提のAIエージェント-AWS登壇資料
kentarofujii
0
120
Automating Web Accessibility Testing with AI Agents
maminami373
0
1k
実運用で考える PGO
kworkdev
PRO
0
150
Featured
See All Featured
We Have a Design System, Now What?
morganepeng
53
7.8k
A Tale of Four Properties
chriscoyier
160
23k
GraphQLとの向き合い方2022年版
quramy
49
14k
How STYLIGHT went responsive
nonsquared
100
5.8k
Dealing with People You Can't Stand - Big Design 2015
cassininazir
367
27k
How to Ace a Technical Interview
jacobian
279
23k
A designer walks into a library…
pauljervisheath
207
24k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
231
53k
Making the Leap to Tech Lead
cromwellryan
135
9.5k
How GitHub (no longer) Works
holman
315
140k
Learning to Love Humans: Emotional Interface Design
aarron
273
40k
The Straight Up "How To Draw Better" Workshop
denniskardys
236
140k
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 でタイポも防げる • 楽できる