Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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

1,037 views

Published on

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

Published in: Engineering
  • Be the first to comment

  • Be the first to like this

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

×