prmdのドキュメントが読みやすくなる話

678 views

Published on

2016/10/18 Ginza.rb 第40回
の発表資料です

Published in: Engineering
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
678
On SlideShare
0
From Embeds
0
Number of Embeds
176
Actions
Shares
0
Downloads
2
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

prmdのドキュメントが読みやすくなる話

  1. 1. prmdのドキュメントが 読みやすくなる話 ota42y 2016/10/18 Ginza.rb 第40回
  2. 2. 自己紹介 ota42y ヘルスケア系の会社勤務 rubyとかgoとかC++とか 最近dartが凄いというウワサ
  3. 3. prmd
  4. 4. prmdとは JSON Schemaのの定義をyamlで書くと 定義の書かれたschemaファイルと ドキュメント用のmarkdown をはき出してくれるgem https://github.com/interagent/prmd
  5. 5. JSON Schemaとは
  6. 6. JSON Schemaとは "title": "index", "description": "Show a list of users.", "href": "/v1/users", "method": "GET", "rel": "show", "targetSchema": { "type": "array", "items": { "$ref": "#/definitions/user/definitions/user" } } } JSONで特定のデータ構造を記述するための仕様 エンドポイントの仕様やリソースの仕様を いい感じに書くのに使える
  7. 7. 何がいいの? 色々あるけど1番は… request&response形式チェックができる comittee(別gem)の導入が必要 documentと実態が同じと保証できる 書くことの利点が上がる メンテされないドキュメントが減る (テストで落ちるので)
  8. 8. prmdの良いところ JSON Schemaをyamlで分割して書ける jsonを直接書かなくて良い JSON Schemaを元にドキュメントを出してくれる 人間が読める APIに関する情報を一カ所に集約できる
  9. 9. サンプル
  10. 10. yaml --- "$schema": http://json-schema.org/draft-04/hyper-schema title: User api description: User information api stability: prototype strictProperties: true type: - object links: - title: index description: Show a list of users. href: "/v1/users" method: GET rel: show targetSchema: type: array items: "$ref": "/schemata/user#/definitions/user"
  11. 11. document
  12. 12. 便利!!(`・∀・´≡`・∀・´)
  13. 13. 今回やったこと prmdはJSON Schemaを全部一個のmarkdownにする 検索性が死ぬ リソース単位でドキュメントにするので、 実際何が何処でできるかわからない
  14. 14. 今回やったこと prmdはJSON Schemaを全部一個のmarkdownにする 検索性が死ぬ リソース単位でドキュメントにするので、 実際何が何処でできるかわからない なのでTOCつけた markdownのトップにリソース名&URL TOCを見れば全体の構成がわかり、探しやすい golang API documentのtype->funcみたいな感じ
  15. 15. TOCの例
  16. 16. 現在の状態 (´・_・`)
  17. 17. 現在の状態 (´・_・`) PRタイトルにWIPってつけてたのにマージされた 同意してくれるのは嬉しいけどWIPとは…
  18. 18. 現在の状態 (´・_・`) PRタイトルにWIPってつけてたのにマージされた 同意してくれるのは嬉しいけどWIPとは… 完成版のPR送ったので、 マージされたら使えるようになります https://github.com/interagent/prmd/pull/312

×