ARI: Improve wiki documentation

This patch improves the documentation of ARI on the wiki. Specifically, it
addresses the following:
* Allowed values and allowed ranges weren't documented. This was particularly
  frustrating, as Asterisk would reject query parameters with disallowed values
  - but we didn't tell anyone what the allowed values were.
* The /play/id operation on /channels and /bridges failed to document all of
  the added media resource types.
* Documentation for creating a channel into a Stasis application failed to
  note when it occurred, and that creating a channel into Stasis conflicts with
  creating a channel into the dialplan.
* Some other minor tweaks in the mustache templates, including italicizing the
  parameter type, putting the default value on its own sub-bullet, and some
  other nicities.

Review: https://reviewboard.asterisk.org/r/4351
........

Merged revisions 431145 from http://svn.asterisk.org/svn/asterisk/branches/13


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@431148 65c4cc65-6c06-0410-ace0-fbb531ad65f3

9 files changed, 68 insertions, 46 deletions

diff --git a/res/ari/resource_bridges.c b/res/ari/resource_bridges.c
index 2dfb1cf9b..9ae0e9386 100644
--- a/res/ari/resource_bridges.c
+++ b/res/ari/resource_bridges.c
@@ -940,8 +940,8 @@ void ast_ari_bridges_create(struct ast_variable *headers,
 		ast_bridge_snapshot_to_json(snapshot, stasis_app_get_sanitizer()));
 }
 
-void ast_ari_bridges_create_or_update_with_id(struct ast_variable *headers,
-	struct ast_ari_bridges_create_or_update_with_id_args *args,
+void ast_ari_bridges_create_with_id(struct ast_variable *headers,
+	struct ast_ari_bridges_create_with_id_args *args,
 	struct ast_ari_response *response)
 {
 	RAII_VAR(struct ast_bridge *, bridge, find_bridge(response, args->bridge_id), ao2_cleanup);
diff --git a/res/ari/resource_bridges.h b/res/ari/resource_bridges.h
index 2b1e7873e..36ff6a017 100644
--- a/res/ari/resource_bridges.h
+++ b/res/ari/resource_bridges.h
@@ -80,8 +80,8 @@ int ast_ari_bridges_create_parse_body(
  * \param[out] response HTTP response
  */
 void ast_ari_bridges_create(struct ast_variable *headers, struct ast_ari_bridges_create_args *args, struct ast_ari_response *response);
-/*! Argument struct for ast_ari_bridges_create_or_update_with_id() */
-struct ast_ari_bridges_create_or_update_with_id_args {
+/*! Argument struct for ast_ari_bridges_create_with_id() */
+struct ast_ari_bridges_create_with_id_args {
 	/*! Comma separated list of bridge type attributes (mixing, holding, dtmf_events, proxy_media) to set. */
 	const char *type;
 	/*! Unique ID to give to the bridge being created. */
@@ -96,9 +96,9 @@ struct ast_ari_bridges_create_or_update_with_id_args {
  * \retval zero on success
  * \retval non-zero on failure
  */
-int ast_ari_bridges_create_or_update_with_id_parse_body(
+int ast_ari_bridges_create_with_id_parse_body(
 	struct ast_json *body,
-	struct ast_ari_bridges_create_or_update_with_id_args *args);
+	struct ast_ari_bridges_create_with_id_args *args);
 
 /*!
  * \brief Create a new bridge or updates an existing one.
@@ -109,7 +109,7 @@ int ast_ari_bridges_create_or_update_with_id_parse_body(
  * \param args Swagger parameters
  * \param[out] response HTTP response
  */
-void ast_ari_bridges_create_or_update_with_id(struct ast_variable *headers, struct ast_ari_bridges_create_or_update_with_id_args *args, struct ast_ari_response *response);
+void ast_ari_bridges_create_with_id(struct ast_variable *headers, struct ast_ari_bridges_create_with_id_args *args, struct ast_ari_response *response);
 /*! Argument struct for ast_ari_bridges_get() */
 struct ast_ari_bridges_get_args {
 	/*! Bridge's id */
@@ -306,7 +306,7 @@ int ast_ari_bridges_play_with_id_parse_body(
 /*!
  * \brief Start playback of media on a bridge.
  *
- * The media URI may be any of a number of URI's. Currently sound: and recording: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)
+ * The media URI may be any of a number of URI's. Currently sound:, recording:, number:, digits:, characters:, and tone: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)
  *
  * \param headers HTTP headers
  * \param args Swagger parameters
diff --git a/res/ari/resource_channels.h b/res/ari/resource_channels.h
index dddfcf3a9..bd3b6205c 100644
--- a/res/ari/resource_channels.h
+++ b/res/ari/resource_channels.h
@@ -54,17 +54,17 @@ void ast_ari_channels_list(struct ast_variable *headers, struct ast_ari_channels
 struct ast_ari_channels_originate_args {
 	/*! Endpoint to call. */
 	const char *endpoint;
-	/*! The extension to dial after the endpoint answers */
+	/*! The extension to dial after the endpoint answers. Mutually exclusive with 'app'. */
 	const char *extension;
-	/*! The context to dial after the endpoint answers. If omitted, uses 'default' */
+	/*! The context to dial after the endpoint answers. If omitted, uses 'default'. Mutually exclusive with 'app'. */
 	const char *context;
-	/*! The priority to dial after the endpoint answers. If omitted, uses 1 */
+	/*! The priority to dial after the endpoint answers. If omitted, uses 1. Mutually exclusive with 'app'. */
 	long priority;
-	/*! The label to dial after the endpoint answers. Will supersede 'priority' if provided. */
+	/*! The label to dial after the endpoint answers. Will supersede 'priority' if provided. Mutually exclusive with 'app'. */
 	const char *label;
-	/*! The application that is subscribed to the originated channel, and passed to the Stasis application. */
+	/*! The application that is subscribed to the originated channel. When the channel is answered, it will be passed to this Stasis application. Mutually exclusive with 'context', 'extension', 'priority', and 'label'. */
 	const char *app;
-	/*! The application arguments to pass to the Stasis application. */
+	/*! The application arguments to pass to the Stasis application provided by 'app'. Mutually exclusive with 'context', 'extension', 'priority', and 'label'. */
 	const char *app_args;
 	/*! CallerID to use when dialing the endpoint or extension. */
 	const char *caller_id;
@@ -119,17 +119,17 @@ struct ast_ari_channels_originate_with_id_args {
 	const char *channel_id;
 	/*! Endpoint to call. */
 	const char *endpoint;
-	/*! The extension to dial after the endpoint answers */
+	/*! The extension to dial after the endpoint answers. Mutually exclusive with 'app'. */
 	const char *extension;
-	/*! The context to dial after the endpoint answers. If omitted, uses 'default' */
+	/*! The context to dial after the endpoint answers. If omitted, uses 'default'. Mutually exclusive with 'app'. */
 	const char *context;
-	/*! The priority to dial after the endpoint answers. If omitted, uses 1 */
+	/*! The priority to dial after the endpoint answers. If omitted, uses 1. Mutually exclusive with 'app'. */
 	long priority;
-	/*! The label to dial after the endpoint answers. Will supersede priority, if provided */
+	/*! The label to dial after the endpoint answers. Will supersede 'priority' if provided. Mutually exclusive with 'app'. */
 	const char *label;
-	/*! The application that is subscribed to the originated channel, and passed to the Stasis application. */
+	/*! The application that is subscribed to the originated channel. When the channel is answered, it will be passed to this Stasis application. Mutually exclusive with 'context', 'extension', 'priority', and 'label'. */
 	const char *app;
-	/*! The application arguments to pass to the Stasis application. */
+	/*! The application arguments to pass to the Stasis application provided by 'app'. Mutually exclusive with 'context', 'extension', 'priority', and 'label'. */
 	const char *app_args;
 	/*! CallerID to use when dialing the endpoint or extension. */
 	const char *caller_id;
@@ -506,7 +506,7 @@ int ast_ari_channels_play_with_id_parse_body(
 /*!
  * \brief Start playback of media and specify the playbackId.
  *
- * The media URI may be any of a number of URI's. Currently sound: and recording: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)
+ * The media URI may be any of a number of URI's. Currently sound:, recording:, number:, digits:, characters:, and tone: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)
  *
  * \param headers HTTP headers
  * \param args Swagger parameters
diff --git a/res/res_ari_bridges.c b/res/res_ari_bridges.c
index 1a91af95b..e0b9f789f 100644
--- a/res/res_ari_bridges.c
+++ b/res/res_ari_bridges.c
@@ -206,9 +206,9 @@ static void ast_ari_bridges_create_cb(
 fin: __attribute__((unused))
 	return;
 }
-int ast_ari_bridges_create_or_update_with_id_parse_body(
+int ast_ari_bridges_create_with_id_parse_body(
 	struct ast_json *body,
-	struct ast_ari_bridges_create_or_update_with_id_args *args)
+	struct ast_ari_bridges_create_with_id_args *args)
 {
 	struct ast_json *field;
 	/* Parse query parameters out of it */
@@ -230,12 +230,12 @@ int ast_ari_bridges_create_or_update_with_id_parse_body(
  * \param headers HTTP headers.
  * \param[out] response Response to the HTTP request.
  */
-static void ast_ari_bridges_create_or_update_with_id_cb(
+static void ast_ari_bridges_create_with_id_cb(
 	struct ast_tcptls_session_instance *ser,
 	struct ast_variable *get_params, struct ast_variable *path_vars,
 	struct ast_variable *headers, struct ast_ari_response *response)
 {
-	struct ast_ari_bridges_create_or_update_with_id_args args = {};
+	struct ast_ari_bridges_create_with_id_args args = {};
 	struct ast_variable *i;
 	RAII_VAR(struct ast_json *, body, NULL, ast_json_unref);
 #if defined(AST_DEVMODE)
@@ -273,11 +273,11 @@ static void ast_ari_bridges_create_or_update_with_id_cb(
 			goto fin;
 		}
 	}
-	if (ast_ari_bridges_create_or_update_with_id_parse_body(body, &args)) {
+	if (ast_ari_bridges_create_with_id_parse_body(body, &args)) {
 		ast_ari_response_alloc_failed(response);
 		goto fin;
 	}
-	ast_ari_bridges_create_or_update_with_id(headers, &args, response);
+	ast_ari_bridges_create_with_id(headers, &args, response);
 #if defined(AST_DEVMODE)
 	code = response->response_code;
 
@@ -1378,7 +1378,7 @@ static struct stasis_rest_handlers bridges_bridgeId = {
 	.path_segment = "bridgeId",
 	.is_wildcard = 1,
 	.callbacks = {
-		[AST_HTTP_POST] = ast_ari_bridges_create_or_update_with_id_cb,
+		[AST_HTTP_POST] = ast_ari_bridges_create_with_id_cb,
 		[AST_HTTP_GET] = ast_ari_bridges_get_cb,
 		[AST_HTTP_DELETE] = ast_ari_bridges_destroy_cb,
 	},
diff --git a/rest-api-templates/api.wiki.mustache b/rest-api-templates/api.wiki.mustache
index de6de2dcc..73aa2448a 100644
--- a/rest-api-templates/api.wiki.mustache
+++ b/rest-api-templates/api.wiki.mustache
@@ -11,21 +11,33 @@ h1. {{name_title}}
 {{#operations}}
 
 {anchor:{{nickname}}}
-h2. {{http_method}} {{wiki_path}}
+h2. {{nickname}}: {{http_method}} {{wiki_path}}
 
 {{{wiki_summary}}}{{#wiki_notes}} {{{wiki_notes}}}{{/wiki_notes}}
 {{#has_path_parameters}}
 
 h3. Path parameters
 {{#path_parameters}}
-* {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} - {{{wiki_description}}}
+* {{name}}: _{{data_type}}_ - {{{wiki_description}}}
+{{#default_value}}
+** Default: {{default_value}}
+{{/default_value}}
+{{#wiki_allowable_values}}
+** {{wiki_allowable_values}}
+{{/wiki_allowable_values}}
 {{/path_parameters}}
 {{/has_path_parameters}}
 {{#has_query_parameters}}
 
 h3. Query parameters
 {{#query_parameters}}
-* {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
+* {{name}}: _{{data_type}}_ -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
+{{#default_value}}
+** Default: {{default_value}}
+{{/default_value}}
+{{#wiki_allowable_values}}
+** {{wiki_allowable_values}}
+{{/wiki_allowable_values}}
 {{#allow_multiple}}
 ** Allows comma separated values.
 {{/allow_multiple}}
diff --git a/rest-api-templates/asterisk_processor.py b/rest-api-templates/asterisk_processor.py
index ef0f1673a..ab8a8afd2 100644
--- a/rest-api-templates/asterisk_processor.py
+++ b/rest-api-templates/asterisk_processor.py
@@ -223,6 +223,10 @@ class AsteriskProcessor(SwaggerPostProcessor):
         else:
             parameter.c_space = ' '
         parameter.wiki_description = wikify(parameter.description)
+        if parameter.allowable_values:
+            parameter.wiki_allowable_values = parameter.allowable_values.to_wiki()
+        else:
+            parameter.wiki_allowable_values = None
 
     def process_model(self, model, context):
         model.description_dox = model.description.replace('\n', '\n * ')
diff --git a/rest-api-templates/swagger_model.py b/rest-api-templates/swagger_model.py
index 9c65219e5..f3b49e12e 100644
--- a/rest-api-templates/swagger_model.py
+++ b/rest-api-templates/swagger_model.py
@@ -220,6 +220,9 @@ class AllowableRange(Stringify):
         self.min_value = min_value
         self.max_value = max_value
 
+    def to_wiki(self):
+        return "Allowed range: Min: {0}; Max: {1}".format(self.min_value, self.max_value)
+
 
 class AllowableList(Stringify):
     """Model of a allowableValues of type LIST
@@ -229,6 +232,9 @@ class AllowableList(Stringify):
     def __init__(self, values):
         self.values = values
 
+    def to_wiki(self):
+        return "Allowed values: {0}".format(", ".join(self.values))
+
 
 def load_allowable_values(json, context):
     """Parse a JSON allowableValues object.
diff --git a/rest-api/api-docs/bridges.json b/rest-api/api-docs/bridges.json
index 21708c839..4f7f72400 100644
--- a/rest-api/api-docs/bridges.json
+++ b/rest-api/api-docs/bridges.json
@@ -60,7 +60,7 @@
 					"httpMethod": "POST",
 					"summary": "Create a new bridge or updates an existing one.",
 					"notes": "This bridge persists until it has been shut down, or Asterisk has been shut down.",
-					"nickname": "create_or_update_with_id",
+					"nickname": "createWithId",
 					"responseClass": "Bridge",
 					"parameters": [
 						{
@@ -398,7 +398,7 @@
 				{
 					"httpMethod": "POST",
 					"summary": "Start playback of media on a bridge.",
-					"notes": "The media URI may be any of a number of URI's. Currently sound: and recording: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
+					"notes": "The media URI may be any of a number of URI's. Currently sound:, recording:, number:, digits:, characters:, and tone: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
 					"nickname": "playWithId",
 					"responseClass": "Playback",
 					"parameters": [
diff --git a/rest-api/api-docs/channels.json b/rest-api/api-docs/channels.json
index 87dee7c84..887191373 100644
--- a/rest-api/api-docs/channels.json
+++ b/rest-api/api-docs/channels.json
@@ -34,7 +34,7 @@
 						},
 						{
 							"name": "extension",
-							"description": "The extension to dial after the endpoint answers",
+							"description": "The extension to dial after the endpoint answers. Mutually exclusive with 'app'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -42,7 +42,7 @@
 						},
 						{
 							"name": "context",
-							"description": "The context to dial after the endpoint answers. If omitted, uses 'default'",
+							"description": "The context to dial after the endpoint answers. If omitted, uses 'default'. Mutually exclusive with 'app'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -50,7 +50,7 @@
 						},
 						{
 							"name": "priority",
-							"description": "The priority to dial after the endpoint answers. If omitted, uses 1",
+							"description": "The priority to dial after the endpoint answers. If omitted, uses 1. Mutually exclusive with 'app'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -58,7 +58,7 @@
 						},
 						{
 							"name": "label",
-							"description": "The label to dial after the endpoint answers. Will supersede 'priority' if provided.",
+							"description": "The label to dial after the endpoint answers. Will supersede 'priority' if provided. Mutually exclusive with 'app'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -66,7 +66,7 @@
 						},
 						{
 							"name": "app",
-							"description": "The application that is subscribed to the originated channel, and passed to the Stasis application.",
+							"description": "The application that is subscribed to the originated channel. When the channel is answered, it will be passed to this Stasis application. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -74,7 +74,7 @@
 						},
 						{
 							"name": "appArgs",
-							"description": "The application arguments to pass to the Stasis application.",
+							"description": "The application arguments to pass to the Stasis application provided by 'app'. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -190,7 +190,7 @@
 						},
 						{
 							"name": "extension",
-							"description": "The extension to dial after the endpoint answers",
+							"description": "The extension to dial after the endpoint answers. Mutually exclusive with 'app'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -198,7 +198,7 @@
 						},
 						{
 							"name": "context",
-							"description": "The context to dial after the endpoint answers. If omitted, uses 'default'",
+							"description": "The context to dial after the endpoint answers. If omitted, uses 'default'. Mutually exclusive with 'app'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -206,7 +206,7 @@
 						},
 						{
 							"name": "priority",
-							"description": "The priority to dial after the endpoint answers. If omitted, uses 1",
+							"description": "The priority to dial after the endpoint answers. If omitted, uses 1. Mutually exclusive with 'app'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -214,7 +214,7 @@
 						},
 						{
 							"name": "label",
-							"description": "The label to dial after the endpoint answers. Will supersede priority, if provided",
+							"description": "The label to dial after the endpoint answers. Will supersede 'priority' if provided. Mutually exclusive with 'app'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -222,7 +222,7 @@
 						},
 						{
 							"name": "app",
-							"description": "The application that is subscribed to the originated channel, and passed to the Stasis application.",
+							"description": "The application that is subscribed to the originated channel. When the channel is answered, it will be passed to this Stasis application. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -230,7 +230,7 @@
 						},
 						{
 							"name": "appArgs",
-							"description": "The application arguments to pass to the Stasis application.",
+							"description": "The application arguments to pass to the Stasis application provided by 'app'. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
@@ -922,7 +922,7 @@
 				{
 					"httpMethod": "POST",
 					"summary": "Start playback of media and specify the playbackId.",
-					"notes": "The media URI may be any of a number of URI's. Currently sound: and recording: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
+					"notes": "The media URI may be any of a number of URI's. Currently sound:, recording:, number:, digits:, characters:, and tone: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
 					"nickname": "playWithId",
 					"responseClass": "Playback",
 					"parameters": [