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
640
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
適材適所の技術選定 〜GraphQL・REST API・tRPC〜 / Optimal Technology Selection
kakehashi
1
710
Adopting Jetpack Compose in Your Existing Project - GDG DevFest Bangkok 2024
akexorcist
0
120
OCI Network Firewall 概要
oracle4engineer
PRO
0
4.2k
Why App Signing Matters for Your Android Apps - Android Bangkok Conference 2024
akexorcist
0
130
TypeScriptの次なる大進化なるか!? 条件型を返り値とする関数の型推論
uhyo
2
1.7k
FlutterアプリにおけるSLI/SLOを用いたユーザー体験の可視化と計測基盤構築
ostk0069
0
120
SDNという名のデータプレーンプログラミングの歴史
ebiken
PRO
2
120
20241120_JAWS_東京_ランチタイムLT#17_AWS認定全冠の先へ
tsumita
2
310
Making your applications cross-environment - OSCG 2024 NA
salaboy
0
200
100 名超が参加した日経グループ横断の競技型 AWS 学習イベント「Nikkei Group AWS GameDay」の紹介/mediajaws202411
nikkei_engineer_recruiting
1
170
Python(PYNQ)がテーマのAMD主催のFPGAコンテストに参加してきた
iotengineer22
0
540
【令和最新版】AWS Direct Connectと愉快なGWたちのおさらい
minorun365
PRO
5
780
Featured
See All Featured
Optimizing for Happiness
mojombo
376
70k
Stop Working from a Prison Cell
hatefulcrawdad
267
20k
5 minutes of I Can Smell Your CMS
philhawksworth
202
19k
Designing Experiences People Love
moore
138
23k
Mobile First: as difficult as doing things right
swwweet
222
8.9k
Put a Button on it: Removing Barriers to Going Fast.
kastner
59
3.5k
Speed Design
sergeychernyshev
25
620
Creating an realtime collaboration tool: Agile Flush - .NET Oxford
marcduiker
25
1.8k
ReactJS: Keep Simple. Everything can be a component!
pedronauck
665
120k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
31
2.7k
How STYLIGHT went responsive
nonsquared
95
5.2k
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
8
900
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 でタイポも防げる • 楽できる