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

1. prmdのドキュメントが
読みやすくなる話
ota42y
2016/10/18 Ginza.rb 第40回

2. 自己紹介
ota42y
ヘルスケア系の会社勤務
rubyとかgoとかC++とか
最近dartが凄いというウワサ

3. prmd

4. prmdとは
JSON Schemaのの定義をyamlで書くと
定義の書かれたschemaファイルと
ドキュメント用のmarkdown
をはき出してくれるgem
https://github.com/interagent/prmd

5. JSON Schemaとは

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. 何がいいの？
色々あるけど1番は…
request&response形式チェックができる
comittee(別gem)の導入が必要
documentと実態が同じと保証できる
書くことの利点が上がる
メンテされないドキュメントが減る
（テストで落ちるので）

8. prmdの良いところ
JSON Schemaをyamlで分割して書ける
jsonを直接書かなくて良い
JSON Schemaを元にドキュメントを出してくれる
人間が読める
APIに関する情報を一カ所に集約できる

9. サンプル

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. document

12. 便利！！(｀・∀・´≡｀・∀・´)

13. 今回やったこと
prmdはJSON Schemaを全部一個のmarkdownにする
検索性が死ぬ
リソース単位でドキュメントにするので、
実際何が何処でできるかわからない

14. 今回やったこと
prmdはJSON Schemaを全部一個のmarkdownにする
検索性が死ぬ
リソース単位でドキュメントにするので、
実際何が何処でできるかわからない
なのでTOCつけた
markdownのトップにリソース名&URL
TOCを見れば全体の構成がわかり、探しやすい
golang API documentのtype->funcみたいな感じ

15. TOCの例

16. 現在の状態
(´・_・`)

17. 現在の状態
(´・_・`)
PRタイトルにWIPってつけてたのにマージされた
同意してくれるのは嬉しいけどWIPとは…

18. 現在の状態
(´・_・`)
PRタイトルにWIPってつけてたのにマージされた
同意してくれるのは嬉しいけどWIPとは…
完成版のPR送ったので、
マージされたら使えるようになります
https://github.com/interagent/prmd/pull/312