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
540
GolangでAPIドキュメント自動生成
社内LT
Masaki Iino
November 17, 2017
Tweet
Share
More Decks by Masaki Iino
See All by Masaki Iino
GCP Composer
iinomasaki
0
220
AnyPay ChatOps
iinomasaki
0
1.2k
Istio
iinomasaki
0
1.5k
LT_Cloud_Functions.pdf
iinomasaki
1
530
Other Decks in Technology
See All in Technology
[新卒向け研修資料] テスト文字列に「うんこ」と入れるな(2024年版)
infiniteloop_inc
4
13k
VSCodeの拡張機能を作っている話
ebarakazuhiro
1
370
DevOpsDays History and my DevOps story
kawaguti
PRO
9
2.5k
TechFeed Experts Night#27 〜 フロントエンドフレームワーク最前線 (Svelte)
baseballyama
1
440
自己改善からチームを動かす! 「セルフエンジニアリングマネージャー」のすゝめ
shoota
6
430
MapLibreとAmazon Location Service
dayjournal
1
150
サーバー間 GraphQL と webmock-graphql の話 / server-to-server graphql and webmock-graphql
qsona
2
180
データベース02: データベースの概念
trycycle
0
150
継続的な改善 x ⾮連続的な進化
sansantech
PRO
3
150
私が trocco を推す理由
__allllllllez__
1
220
EMとして2023年度に頑張ったこと / What we did well in FY2023 as a EM
pauli
1
170
Vertex AI を中心に 生成AIのアップデートを共有します
kaz1437
0
300
Featured
See All Featured
It's Worth the Effort
3n
180
27k
Docker and Python
trallard
34
2.7k
Facilitating Awesome Meetings
lara
42
5.6k
Building a Modern Day E-commerce SEO Strategy
aleyda
17
6.4k
Into the Great Unknown - MozCon
thekraken
10
990
Designing for humans not robots
tammielis
248
25k
Building an army of robots
kneath
300
41k
Product Roadmaps are Hard
iamctodd
44
9.7k
Raft: Consensus for Rubyists
vanstee
132
6.3k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
tammyeverts
14
1.6k
The Invisible Customer
myddelton
114
12k
How to name files
jennybc
65
93k
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 でタイポも防げる • 楽できる