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
620
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
サプライチェーン攻撃に備える
ryunen344
0
390
アプリをリリースできる状態に保ったまま 段階的にリファクタリングするための 戦略と戦術 / Strategies and tactics for incremental refactoring
yanzm
6
1.5k
急拡大する開発組織を支えるナレッジワークの E2E テスト基盤
kworkdev
PRO
0
120
サーバー管理しないサーバーサービスManaged DevOps Pool
kkamegawa
0
140
20240912 JJUGナイトセミナー
mii1004
0
140
プログラム検証入門
riru
6
890
LINEヤフーのフロントエンド組織・体制の紹介
lycorp_recruit_jp
1
1.2k
学術機関におけるID連携とOpenID Connect
fujie
0
320
eBPFのこれまでとこれから
yutarohayakawa
10
3.3k
プロダクトエンジニアを支えるための開発生産性向上施策
tsukakei
0
150
Oracle Base Database Service 技術詳細
oracle4engineer
PRO
5
46k
エムスリーエビデンス創出プロダクトチーム紹介資料 / Introduction of M3 Create Evidence Team
m3_engineering
0
130
Featured
See All Featured
Embracing the Ebb and Flow
colly
83
4.4k
YesSQL, Process and Tooling at Scale
rocio
167
14k
Save Time (by Creating Custom Rails Generators)
garrettdimon
PRO
24
610
[Rails World 2023 - Day 1 Closing Keynote] - The Magic of Rails
eileencodes
28
1.6k
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
29
2.2k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
36
1.7k
StorybookのUI Testing Handbookを読んだ
zakiyama
26
5.1k
Faster Mobile Websites
deanohume
304
30k
Reflections from 52 weeks, 52 projects
jeffersonlam
346
20k
Thoughts on Productivity
jonyablonski
66
4.2k
Web development in the modern age
philhawksworth
205
10k
Optimising Largest Contentful Paint
csswizardry
31
2.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 でタイポも防げる • 楽できる