ARI: Improve wiki documentation
authorMatthew Jordan <mjordan@digium.com>
Tue, 27 Jan 2015 17:21:03 +0000 (17:21 +0000)
committerMatthew Jordan <mjordan@digium.com>
Tue, 27 Jan 2015 17:21:03 +0000 (17:21 +0000)
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

res/ari/resource_bridges.c
res/ari/resource_bridges.h
res/ari/resource_channels.h
res/res_ari_bridges.c
rest-api-templates/api.wiki.mustache
rest-api-templates/asterisk_processor.py
rest-api-templates/swagger_model.py
rest-api/api-docs/bridges.json
rest-api/api-docs/channels.json

index 2dfb1cf..9ae0e93 100644 (file)
@@ -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);
index 2b1e787..36ff6a0 100644 (file)
@@ -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
index dddfcf3..bd3b620 100644 (file)
@@ -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
index 1a91af9..e0b9f78 100644 (file)
@@ -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,
        },
index de6de2d..73aa244 100644 (file)
@@ -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}}
index ef0f167..ab8a8af 100644 (file)
@@ -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 * ')
index 9c65219..f3b49e1 100644 (file)
@@ -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.
index 21708c8..4f7f724 100644 (file)
@@ -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": [
                                                {
                                {
                                        "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": [
index 87dee7c..8871913 100644 (file)
@@ -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,
                                                },
                                                {
                                                        "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,
                                                },
                                                {
                                                        "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,
                                                },
                                                {
                                                        "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,
                                                },
                                                {
                                                        "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,
                                                },
                                                {
                                                        "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,
                                                },
                                                {
                                                        "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,
                                {
                                        "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": [