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
730
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
ヘンリー会社紹介資料(エンジニア向け) / company deck for engineer
henryofficial
0
350
OTEPsで知るOpenTelemetryの未来 / Observability Conference Tokyo 2025
arthur1
0
120
ソースを読むプロセスの例
sat
PRO
15
9.9k
Linux カーネルが支えるコンテナの仕組み / LF Japan Community Days 2025 Osaka
tenforward
1
120
マルチエージェントのチームビルディング_2025-10-25
shinoyamada
0
120
Oracle Base Database Service 技術詳細
oracle4engineer
PRO
12
81k
QA業務を変える(!?)AIを併用した不具合分析の実践
ma2ri
0
140
Contract One Engineering Unit 紹介資料
sansan33
PRO
0
9k
AI時代におけるデータの重要性 ~データマネジメントの第一歩~
ryoichi_ota
0
710
Data Hubグループ 紹介資料
sansan33
PRO
0
2.2k
Wasmの気になる最新情報
askua
0
190
あなたの知らない Linuxカーネル脆弱性の世界
recruitengineers
PRO
3
150
Featured
See All Featured
Mobile First: as difficult as doing things right
swwweet
225
10k
Designing Experiences People Love
moore
142
24k
The MySQL Ecosystem @ GitHub 2015
samlambert
251
13k
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
34
2.5k
The Art of Programming - Codeland 2020
erikaheidi
56
14k
Code Review Best Practice
trishagee
72
19k
Navigating Team Friction
lara
190
15k
Building Applications with DynamoDB
mza
96
6.7k
The Pragmatic Product Professional
lauravandoore
36
7k
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
26
3.1k
Fantastic passwords and where to find them - at NoRuKo
philnash
52
3.5k
We Have a Design System, Now What?
morganepeng
53
7.8k
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 でタイポも防げる • 楽できる