KAZOO-5248: keep doc schemas in sync with ref/ (#3021)

* KAZOO-5248: segregate schemas in ref docs * KAZOO-5248: add missing schemas * KAZOO-5248: fix assoc * KAZOO-5248: add missing schema * KAZOO-5248: fix spacing in faxes.md * KAZOO-5248: amend `make apis` * KAZOO-5248: make apis * KAZOO-5248: use os.path.dirname/basename
2600hz · Dec 21, 2016 · a5db2f7 · a5db2f7
1 parent 882df68
commit a5db2f7
Show file tree

Hide file tree

Showing 86 changed files with 1,945 additions and 109 deletions.
diff --git a/Makefile b/Makefile
@@ -189,6 +189,7 @@ apis:
 	@ERL_LIBS=deps/:core/:applications/ $(ROOT)/scripts/generate-schemas.escript
 	@$(ROOT)/scripts/format-json.sh applications/crossbar/priv/couchdb/schemas/*.json
 	@ERL_LIBS=deps/:core/:applications/ $(ROOT)/scripts/generate-api-endpoints.escript
+	@$(ROOT)/scripts/generate-doc-schemas.sh applications/crossbar/doc/ref/*.md
 	@$(ROOT)/scripts/format-json.sh applications/crossbar/priv/api/swagger.json
 	@$(ROOT)/scripts/format-json.sh applications/crossbar/priv/api/*.json
 	@ERL_LIBS=deps/:core/:applications/ $(ROOT)/scripts/generate-fs-headers-hrl.escript

diff --git a/applications/crossbar/doc/access_lists.md b/applications/crossbar/doc/access_lists.md
@@ -18,6 +18,8 @@ Sections:
 
 #### Schema
 
+Access Control List entries for device or account
+
 Key | Description | Type | Default | Required
 --- | ----------- | ---- | ------- | --------
 `cidrs` | Classless Inter-Domain Routing IP notation for use on the access lists | `array(string)` |   | `true`
@@ -26,6 +28,8 @@ Key | Description | Type | Default | Required
 `user_agent` | RegExp to match valid user agent strings | `string` |   | `false`
 
 
+
+
 #### Remove account-level access lists
 
 > DELETE /v2/accounts/{ACCOUNT_ID}/access_lists

diff --git a/applications/crossbar/doc/accounts.md b/applications/crossbar/doc/accounts.md
@@ -12,31 +12,298 @@ So given `"pvt_tree":["1", "2", "3"]`, it can be determined that "3" is the pare
 
 #### Schema
 
+Accounts represent tenants or customers on the system. Each account represents an individual dataset or sandbox that only one tenant can access. The data set is architecturally independent from other tenants.
+
 Key | Description | Type | Default | Required
 --- | ----------- | ---- | ------- | --------
 `call_restriction` | Account level call restrictions for each available number classification | `object` | `{}` | `false`
-`call_waiting` |   | `#/definitions/call_waiting` |   | `false`
+`call_waiting` |   | [#/definitions/call_waiting](#call_waiting) |   | `false`
 `caller_id` | The account default caller ID parameters | `object` | `{}` | `false`
 `dial_plan` | A list of default rules used to modify dialed numbers | `object` | `{}` | `false`
 `do_not_disturb` |   | `object` |   | `false`
 `do_not_disturb.enabled` | The default value for do-not-disturb | `boolean` |   | `false`
 `enabled` | Determines if the account is currently enabled | `boolean` | `true` | `false`
 `language` | The language for this account | `string` | `en-us` | `false`
-`metaflows` |   | `#/definitions/metaflows` |   | `false`
+`metaflows` |   | [#/definitions/metaflows](#metaflows) |   | `false`
 `music_on_hold` | The default music on hold parameters | `object` | `{}` | `false`
 `music_on_hold.media_id` | The ID of a media object that should be used as the default music on hold | `string(0..128)` |   | `false`
 `name` | A friendly name for the account | `string(1..128)` |   | `true`
 `org` | Full legal name of the organization | `string` |   | `false`
 `preflow` | Each property provides functionality that can be applied to calls using the callflow application | `object` | `{}` | `false`
 `preflow.always` | The ID of a callflow to always execute prior to processing the callflow with numbers/patterns matching the request | `string` |   | `false`
 `realm` | The realm of the account, ie: 'account1.2600hz.com' | `string(4..253)` |   | `false`
-`ringtones` |   | `object` | `{}` | `false`
+`ringtones` | Ringtone Parameters | `object` | `{}` | `false`
 `ringtones.external` | The alert info SIP header added when the call is from internal sources | `string(0..256)` |   | `false`
 `ringtones.internal` | The alert info SIP header added when the call is from external sources | `string(0..256)` |   | `false`
-`timezone` | The default timezone | `string(5..32)` | `America/Los_Angeles` | `false`
+`timezone` | The default timezone | `string(5..32)` |   | `false`
 `voicemail` |   | `object` |   | `false`
 `voicemail.notify` |   | `object` |   | `false`
-`voicemail.notify.callback` |   | `#/definitions/notify.callback` |   | `false`
+`voicemail.notify.callback` |   | [#/definitions/notify.callback](#notifycallback) |   | `false`
+
+
+##### call_waiting
+
+Parameters for server-side call waiting
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`enabled` | Determines if server side call waiting is enabled/disabled | `boolean` |   | `false`
+
+##### caller_id
+
+Defines caller ID settings based on the type of call being made
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`emergency` | The caller ID used when a resource is flagged as 'emergency' | `object` |   | `false`
+`emergency.name` | The caller id name for the object type | `string(0..35)` |   | `false`
+`emergency.number` | The caller id name for the object type | `string(0..35)` |   | `false`
+`external` | The default caller ID used when dialing external numbers | `object` |   | `false`
+`external.name` | The caller id name for the object type | `string(0..35)` |   | `false`
+`external.number` | The caller id name for the object type | `string(0..35)` |   | `false`
+`internal` | The default caller ID used when dialing internal extensions | `object` |   | `false`
+`internal.name` | The caller id name for the object type | `string(0..35)` |   | `false`
+`internal.number` | The caller id name for the object type | `string(0..35)` |   | `false`
+
+##### dialplans
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`system` | List of system dial plans | `array()` |   | `false`
+
+##### metaflow
+
+A metaflow node defines a module to execute, data to provide to that module, and one or more children to branch to
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+
+##### metaflow.audio_level
+
+audio_level metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `true`
+`data.action` |   | `string` |   | `true`
+`data.level` |   | `string` |   | `false`
+`data.mode` |   | `string` |   | `false`
+`module` |   | `string('audio_level')` |   | `true`
+
+##### metaflow.break
+
+break metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `false`
+`module` |   | `string('break')` |   | `true`
+
+##### metaflow.callflow
+
+callflow metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `true`
+`data.id` |   | `string` |   | `true`
+`module` |   | `string('callflow')` |   | `true`
+
+##### metaflow.hangup
+
+hangup metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `false`
+`module` |   | `string('hangup')` |   | `true`
+
+##### metaflow.hold
+
+hold metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `true`
+`data.moh_aleg` |   | `string` |   | `false`
+`data.moh_bleg` |   | `string` |   | `false`
+`data.unhold_key` |   | `string` | `1` | `false`
+`module` |   | `string('hold')` |   | `true`
+
+##### metaflow.hold_control
+
+hold_control metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `false`
+`data.action` |   | `string('hold', 'unhold', 'toggle')` | `toggle` | `false`
+`module` |   | `string('hold_control')` |   | `true`
+
+##### metaflow.intercept
+
+intercept metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `true`
+`data.auto_answer` |   | `boolean` | `false` | `false`
+`data.target_id` |   | `string` |   | `true`
+`data.target_type` |   | `string('device', 'user', 'number')` |   | `true`
+`data.unbridged_only` |   | `boolean` | `true` | `false`
+`module` |   | `string('intercept')` |   | `true`
+
+##### metaflow.move
+
+move metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `true`
+`data.auto_answer` |   | `boolean` | `false` | `false`
+`data.device_id` |   | `string` |   | `false`
+`data.owner_id` |   | `string` |   | `false`
+`module` |   | `string('move')` |   | `true`
+
+##### metaflow.play
+
+play metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `true`
+`data.id` |   | `string` |   | `true`
+`data.leg` |   | `string('both', 'self', 'peer')` | `both` | `false`
+`module` |   | `string('play')` |   | `true`
+
+##### metaflow.record_call
+
+record_call metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `true`
+`data.action` |   | `string('start', 'stop', 'toggle')` | `toggle` | `true`
+`data.format` |   | `string` |   | `false`
+`data.media_name` |   | `string` |   | `false`
+`module` |   | `string('record_call')` |   | `true`
+
+##### metaflow.resume
+
+resume metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `false`
+`module` |   | `string('resume')` |   | `true`
+
+##### metaflow.say
+
+say metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `true`
+`data.language` |   | `string` |   | `false`
+`data.method` |   | `string` |   | `false`
+`data.text` |   | `string` |   | `true`
+`data.type` |   | `string` |   | `false`
+`module` |   | `string('say')` |   | `true`
+
+##### metaflow.sound_touch
+
+sound_touch metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `true`
+`data.action` |   | `string('start', 'stop')` |   | `true`
+`data.adjust_in_octaves` |   | `integer` |   | `false`
+`data.adjust_in_semitones` |   | `integer` |   | `false`
+`data.hook_dtmf` |   | `boolean` | `false` | `false`
+`data.pitch` |   | `integer` |   | `false`
+`data.rate` |   | `integer` |   | `false`
+`data.sending_leg` |   | `boolean` | `false` | `false`
+`data.tempo` |   | `integer` |   | `false`
+`module` |   | `string('sound_touch')` |   | `true`
+
+##### metaflow.transfer
+
+transfer metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `true`
+`data.Transfer-Type` |   | `string` | `attended` | `false`
+`data.captures` |   | `string` |   | `false`
+`data.target` |   | `string` |   | `false`
+`module` |   | `string('transfer')` |   | `true`
+
+##### metaflow.tts
+
+tts metaflow schema
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`children` |   | [#/definitions/metaflow_children](#metaflow_children) |   | `false`
+`data` |   | `object` |   | `true`
+`data.engine` |   | `string` | `flite` | `false`
+`data.language` |   | `string` |   | `false`
+`data.leg` |   | `string` | `self` | `false`
+`data.terminators` |   | `string` |   | `false`
+`data.text` |   | `string` |   | `true`
+`data.voice` |   | `string` | `female` | `false`
+`module` |   | `string('tts')` |   | `true`
+
+##### metaflow_children
+
+A metaflow child nodes
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+
+##### metaflows
+
+Actions applied to a call outside of the normal callflow, initiated by the caller(s)
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`binding_digit` | What DTMF will trigger the collection and analysis of the subsequent DTMF sequence | `string('1', '2', '3', '4', '5', '6', '7', '8', '9', '0', '*', '#')` | `*` | `false`
+`digit_timeout` | How long to wait between DTMF presses before processing the collected sequence (milliseconds) | `integer` |   | `false`
+`listen_on` | Which leg(s) of the call to listen for DTMF | `string('both', 'self', 'peer')` |   | `false`
+`numbers` | A list of static numbers with their flows | `object` |   | `false`
+`numbers./^[0-9]+$/` |   | [#/definitions/metaflow](#metaflow) |   | `false`
+`patterns` | A list of patterns with their flows | `object` |   | `false`
+`patterns./.+/` |   | [#/definitions/metaflow](#metaflow) |   | `false`
+
+##### notify.callback
+
+Schema for a callback options
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`attempts` | How many attempts without answer will system do | `integer` |   | `false`
+`disabled` | Determines if the system will call to callback number | `boolean` |   | `false`
+`interval_s` | How long will system wait between call back notification attempts | `integer` |   | `false`
+`number` | Number for callback notifications about new messages | `string` |   | `false`
+`schedule` | Schedules interval between callbacks | `array(integer)` |   | `false`
+`timeout_s` | How long will system wait for answer to callback | `integer` |   | `false`
+
+
 
 #### Create a new child account
 

diff --git a/applications/crossbar/doc/allotments.md b/applications/crossbar/doc/allotments.md
@@ -8,6 +8,8 @@ Key | Description | Type | Default | Required
 --- | ----------- | ---- | ------- | --------
 
 
+
+
 #### Get allotments configuration for a given account
 
 > GET /v2/accounts/{ACCOUNT_ID}/allotments