[svn-commits] mjordan: trunk r431148 - in /trunk: ./ res/ res/ari/ rest-api-templates/ rest...
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Tue Jan 27 11:21:09 CST 2015
Author: mjordan
Date: Tue Jan 27 11:21:03 2015
New Revision: 431148
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=431148
Log:
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
Modified:
trunk/ (props changed)
trunk/res/ari/resource_bridges.c
trunk/res/ari/resource_bridges.h
trunk/res/ari/resource_channels.h
trunk/res/res_ari_bridges.c
trunk/rest-api-templates/api.wiki.mustache
trunk/rest-api-templates/asterisk_processor.py
trunk/rest-api-templates/swagger_model.py
trunk/rest-api/api-docs/bridges.json
trunk/rest-api/api-docs/channels.json
Propchange: trunk/
------------------------------------------------------------------------------
Binary property 'branch-13-merged' - no diff available.
Modified: trunk/res/ari/resource_bridges.c
URL: http://svnview.digium.com/svn/asterisk/trunk/res/ari/resource_bridges.c?view=diff&rev=431148&r1=431147&r2=431148
==============================================================================
--- trunk/res/ari/resource_bridges.c (original)
+++ trunk/res/ari/resource_bridges.c Tue Jan 27 11:21:03 2015
@@ -940,8 +940,8 @@
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);
Modified: trunk/res/ari/resource_bridges.h
URL: http://svnview.digium.com/svn/asterisk/trunk/res/ari/resource_bridges.h?view=diff&rev=431148&r1=431147&r2=431148
==============================================================================
--- trunk/res/ari/resource_bridges.h (original)
+++ trunk/res/ari/resource_bridges.h Tue Jan 27 11:21:03 2015
@@ -80,8 +80,8 @@
* \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 @@
* \retval zero on success
* \retval non-zero on failure
*/
-int ast_ari_bridges_create_or_update_with_id_parse_body(
- struct ast_json *body,
- struct ast_ari_bridges_create_or_update_with_id_args *args);
+int ast_ari_bridges_create_with_id_parse_body(
+ struct ast_json *body,
+ struct ast_ari_bridges_create_with_id_args *args);
/*!
* \brief Create a new bridge or updates an existing one.
@@ -109,7 +109,7 @@
* \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 @@
/*!
* \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
Modified: trunk/res/ari/resource_channels.h
URL: http://svnview.digium.com/svn/asterisk/trunk/res/ari/resource_channels.h?view=diff&rev=431148&r1=431147&r2=431148
==============================================================================
--- trunk/res/ari/resource_channels.h (original)
+++ trunk/res/ari/resource_channels.h Tue Jan 27 11:21:03 2015
@@ -54,17 +54,17 @@
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 @@
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 @@
/*!
* \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
Modified: trunk/res/res_ari_bridges.c
URL: http://svnview.digium.com/svn/asterisk/trunk/res/res_ari_bridges.c?view=diff&rev=431148&r1=431147&r2=431148
==============================================================================
--- trunk/res/res_ari_bridges.c (original)
+++ trunk/res/res_ari_bridges.c Tue Jan 27 11:21:03 2015
@@ -206,9 +206,9 @@
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 @@
* \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 @@
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 @@
.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,
},
Modified: trunk/rest-api-templates/api.wiki.mustache
URL: http://svnview.digium.com/svn/asterisk/trunk/rest-api-templates/api.wiki.mustache?view=diff&rev=431148&r1=431147&r2=431148
==============================================================================
--- trunk/rest-api-templates/api.wiki.mustache (original)
+++ trunk/rest-api-templates/api.wiki.mustache Tue Jan 27 11:21:03 2015
@@ -11,21 +11,33 @@
{{#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}}
Modified: trunk/rest-api-templates/asterisk_processor.py
URL: http://svnview.digium.com/svn/asterisk/trunk/rest-api-templates/asterisk_processor.py?view=diff&rev=431148&r1=431147&r2=431148
==============================================================================
--- trunk/rest-api-templates/asterisk_processor.py (original)
+++ trunk/rest-api-templates/asterisk_processor.py Tue Jan 27 11:21:03 2015
@@ -223,6 +223,10 @@
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 * ')
Modified: trunk/rest-api-templates/swagger_model.py
URL: http://svnview.digium.com/svn/asterisk/trunk/rest-api-templates/swagger_model.py?view=diff&rev=431148&r1=431147&r2=431148
==============================================================================
--- trunk/rest-api-templates/swagger_model.py (original)
+++ trunk/rest-api-templates/swagger_model.py Tue Jan 27 11:21:03 2015
@@ -220,6 +220,9 @@
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
@@ -228,6 +231,9 @@
"""
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):
Modified: trunk/rest-api/api-docs/bridges.json
URL: http://svnview.digium.com/svn/asterisk/trunk/rest-api/api-docs/bridges.json?view=diff&rev=431148&r1=431147&r2=431148
==============================================================================
--- trunk/rest-api/api-docs/bridges.json (original)
+++ trunk/rest-api/api-docs/bridges.json Tue Jan 27 11:21:03 2015
@@ -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": [
Modified: trunk/rest-api/api-docs/channels.json
URL: http://svnview.digium.com/svn/asterisk/trunk/rest-api/api-docs/channels.json?view=diff&rev=431148&r1=431147&r2=431148
==============================================================================
--- trunk/rest-api/api-docs/channels.json (original)
+++ trunk/rest-api/api-docs/channels.json Tue Jan 27 11:21:03 2015
@@ -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": [
More information about the svn-commits
mailing list