23 Commits (8149554e9004c2a37e2fa8ca26dbe19d99241229)

Author	SHA1	Message	Date
George Joseph	5470a23b48	swagger_model.py: Fix invalid escape sequence in get_list_parameter_type(). ... Recent python versions complain when backslashes in strings create invalid escape sequences. This causes issues for strings used as regex patterns like `'^List\[(.*)\]$'` where you want the regex parser to treat `[` and `]` as literals. Double-backslashing is one way to fix it but simply converting the string to a raw string `re.match(r'^List\[(.*)\]$', text)` is easier and less error prone.	8 months ago
George Joseph	3868f7cb47	docs: Enable since/version handling for XML, CLI and ARI documentation ... * Added the "since" element to the XML configObject and configOption elements in appdocsxml.dtd. * Added the "Since" section to the following CLI output: ``` config show help <module> <object> config show help <module> <object> <option> core show application <app> core show function <func> manager show command <command> manager show event <event> agi show commands topic <topic> ``` * Refactored the commands above to output their sections in the same order: Synopsis, Since, Description, Syntax, Arguments, SeeAlso * Refactored the commands above so they all use the same pattern for writing the output to the CLI. * Fixed several memory leaks caused by failure to free temporary output buffers. * Added a "since" array to the mustache template for the top-level resources (Channel, Endpoint, etc.) and to the paths/methods underneath them. These will be added to the generated markdown if present. Example: ``` "resourcePath": "/api-docs/channels.{format}", "requiresModules": [ "res_stasis_answer", "res_stasis_playback", "res_stasis_recording", "res_stasis_snoop" ], "since": [ "18.0.0", "21.0.0" ], "apis": [ { "path": "/channels", "description": "Active channels", "operations": [ { "httpMethod": "GET", "since": [ "18.6.0", "21.8.0" ], "summary": "List all active channels in Asterisk.", "nickname": "list", "responseClass": "List[Channel]" }, ``` NOTE: No versioning information is actually added in this commit. Those will be added separately and instructions for adding and maintaining them will be published on the documentation site at a later date.	10 months ago
George Joseph	1862a36c3b	ari-stubs: Fix more local anchor references ... Also allow CreateDocs job to be run manually with default branches.	2 years ago
George Joseph	8ce313c5b3	ari-stubs: Fix broken documentation anchors ... All of the links that reference page anchors with capital letters in the ids (#Something) have been changed to lower case to match the anchors that are generated by mkdocs.	2 years ago
George Joseph	359f9434de	rest-api: Updates for new documentation site ... The new documentation site uses traditional markdown instead of the Confluence flavored version. This required changes in the mustache templates and the python that generates the files.	2 years ago
Corey Farrell	879e592baf	Build System: Enable python3 compatibility. ... * Consistently use spaces in rest-api-templates/asterisk_processor.py. * Exclude third-party from docs/full-en_US.xml. * Add docs/full-en_US.xml to .gitignore. * Use list() to convert python3 view. * Use python3 print function. * Replace cmp() with equivalent equation. * Replace reference to out of scope subtype variable with name parameter. * Use unescaping triple bracket notation in mustache templates where needed. This causes behavior of Python2 to be maintained when using Python3. * Fix references to has_websocket / is_websocket in res_ari_resource.c.mustache. * Update calculation of has_websocket to use any(). * Use unicode mode for writing output file in transform.py. * Replace 'from swagger_model import *' with explicit import of required symbols. I have not tested spandspflow2pcap.py or voicemailpwcheck.py, only the print syntax has been fixed. Change-Id: If5c5b556a2800d41a3e2cfef080ac2e151178c33	8 years ago
Corey Farrell	679fa5fb34	Add missing OPTIONAL_API and ARI dependences. ... I've audited all modules that include any header which includes asterisk/optional_api.h. All modules which use OPTIONAL_API now declare those dependencies in AST_MODULE_INFO using requires or optional_modules as appropriate. In addition ARI dependency declarations have been reworked. Instead of declaring additional required modules in res/ari/resource_*.c we now add them to an optional array "requiresModules" in api-docs for each module. This allows the AST_MODULE_INFO dependencies to include those missing modules. Change-Id: Ia0c70571f5566784f63605e78e1ceccb4f79c606	8 years ago
Tzafrir Cohen	bab253ac9f	Fixes to various issues reported by pyflakes ... Pyflake is a python (2) source checker. This patch fixes various (mostly trivial) errors and warnings it reports. Change-Id: Ia35c5ac61751b927814cf693994c632c412386ea	9 years ago
Kevin Harwell	7ea133f2ab	rest-api: Swagger scripts were not replacing format variable in file brief ... Given resource paths did not have 'json' substituted in for the '{format}'. For some auto generated documentation/comment strings it resulted in something like the following: "... REST handler for /api-docs/sounds.{format}" This patch makes sure the resource api's path is properly substituted. ASTERISK-25472 #close Change-Id: Ie3e950a35db4043e284019d6c9061f3b03922e23	9 years ago
Matt Jordan	e773e3a9bb	ARI: Add the ability to download the media associated with a stored recording ... This patch adds a new feature to ARI that allows a client to download the media associated with a stored recording. The new route is /recordings/stored/{name}/file, and transmits the underlying binary file using Asterisk's HTTP server's underlying file transfer facilities. Because this REST route returns non-JSON, a few small enhancements had to be made to the Python Swagger generation code, as well as the mustache templates that generate the ARI bindings. ASTERISK-26042 #close Change-Id: I49ec5c4afdec30bb665d9c977ab423b5387e0181	10 years ago
Matthew Jordan	fb8a2e0399	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	11 years ago
Sam Galarneau	5db3f38d5a	api.wiki.mustache: Update wiki template to support body parameters ... This patch updates the api.wiki.mustache template and the swagger_model python script to understand if an operation has a body parameter. If an operation does have a body parameter, it will now be displayed in the corresponding wiki entry. ........ Merged revisions 407389 from http://svn.asterisk.org/svn/asterisk/branches/12 git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@417877 65c4cc65-6c06-0410-ace0-fbb531ad65f3	11 years ago
David M. Lee	fccb427c88	ari:Add application/json parameter support ... The patch allows ARI to parse request parameters from an incoming JSON request body, instead of requiring the request to come in as query parameters (which is just weird for POST and DELETE) or form parameters (which is okay, but a bit asymmetric given that all of our responses are JSON). For any operation that does _not_ have a parameter defined of type body (i.e. "paramType": "body" in the API declaration), if a request provides a request body with a Content type of "application/json", the provided JSON document is parsed and searched for parameters. The expected fields in the provided JSON document should match the query parameters defined for the operation. If the parameter has 'allowMultiple' set, then the field in the JSON document may optionally be an array of values. (closes issue ASTERISK-22685) Review: https://reviewboard.asterisk.org/r/2994/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@403177 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	7d0d1a1efb	ari: User better nicknames for ARI operations ... While working on building client libraries from the Swagger API, I noticed a problem with the nicknames. channel.deleteChannel() channel.answerChannel() channel.muteChannel() Etc. We put the object name in the nickname (since we were generating C code), but it makes OO generators redundant. This patch makes the nicknames more OO friendly. This resulted in a lot of name changing within the res_ari_*.so modules, but not much else. There were a couple of other fixed I made in the process. * When reversible operations (POST /hold, POST /unhold) were made more RESTful (POST /hold, DELETE /unhold), the path for the second operation was left in the API declaration. This worked, but really the two operations should have been on the same API. * The POST /unmute operation had still not been REST-ified. Review: https://reviewboard.asterisk.org/r/2940/ ........ Merged revisions 402528 from http://svn.asterisk.org/svn/asterisk/branches/12 git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@402529 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	32b4e79434	The Swagger 1.2 specification for type extension ended up being ... slightly different than my proposal. Instead of putting an 'extends' field on the subtype, the base type has a 'subTypes' field, which is a list of the subTypes. Given that its a messaging model and not an object model, kinda makes sense. This patch changes the events.json api-doc, and the python translators to take the new format into account. Other changes that are in Swagger 1.2 were not adopted, since the spec is still in flux, and could change before it's finalized. A summary of changes to the Swagger-1.2 spec can be found at https://github.com/wordnik/swagger-core/wiki/1.2-transition. (closes issue ASTERISK-22440) Review: https://reviewboard.asterisk.org/r/2909/ ........ Merged revisions 401701 from http://svn.asterisk.org/svn/asterisk/branches/12 git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@401834 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	9bed50db41	optional_api: Fix linking problems between modules that export global symbols ... With the new work in Asterisk 12, there are some uses of the optional_api that are prone to failure. The details are rather involved, and captured on [the wiki][1]. This patch addresses the issue by removing almost all of the magic from the optional API implementation. Instead of relying on weak symbol resolution, a new optional_api.c module was added to Asterisk core. For modules providing an optional API, the pointer to the implementation function is registered with the core. For modules that use an optional API, a pointer to a stub function, along with a optional_ref function pointer are registered with the core. The optional_ref function pointers is set to the implementation function when it's provided, or the stub function when it's now. Since the implementation no longer relies on magic, it is now supported on all platforms. In the spirit of choice, an OPTIONAL_API flag was added, so we can disable the optional_api if needed (maybe it's buggy on some bizarre platform I haven't tested on) The AST_OPTIONAL_API*() macros themselves remained unchanged, so existing code could remain unchanged. But to help with debugging the optional_api, the patch limits the #include of optional API's to just the modules using the API. This also reduces resource waste maintaining optional_ref pointers that aren't used. Other changes made as a part of this patch: * The stubs for http_websocket that wrap system calls set errno to ENOSYS. * res_http_websocket now properly increments module use count. * In loader.c, the while() wrappers around dlclose() were removed. The while(!dlclose()) is actually an anti-pattern, which can lead to infinite loops if the module you're attempting to unload exports a symbol that was directly linked to. * The special handling of nonoptreq on systems without weak symbol support was removed, since we no longer rely on weak symbols for optional_api. [1]: https://wiki.asterisk.org/wiki/x/wACUAQ (closes issue ASTERISK-22296) Reported by: Matt Jordan Review: https://reviewboard.asterisk.org/r/2797/ ........ Merged revisions 397989 from http://svn.asterisk.org/svn/asterisk/branches/12 git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@397990 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	a75fd32212	ARI - channel recording support ... This patch is the first step in adding recording support to the Asterisk REST Interface. Recordings are stored in /var/spool/recording. Since recordings may be destructive (overwriting existing files), the API rejects attempts to escape the recording directory (avoiding issues if someone attempts to record to ../../lib/sounds/greeting, for example). (closes issue ASTERISK-21594) (closes issue ASTERISK-21581) Review: https://reviewboard.asterisk.org/r/2612/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@393550 65c4cc65-6c06-0410-ace0-fbb531ad65f3	13 years ago
David M. Lee	c9a3d4562d	Update events to use Swagger 1.3 subtyping, and related aftermath ... This patch started with the simple idea of changing the /events data model to be more sane. The original model would send out events like: { "stasis_start": { "args": [], "channel": { ... } } } The event discriminator was the field name instead of being a value in the object, due to limitations in how Swagger 1.1 could model objects. While technically sufficient in communicating event information, it was really difficult to deal with in terms of client side JSON handling. This patch takes advantage of a proposed extension[1] to Swagger which allows type variance through the use of a discriminator field. This had a domino effect that made this a surprisingly large patch. [1]: https://groups.google.com/d/msg/wordnik-api/EC3rGajE0os/ey_5dBI_jWcJ In changing the models, I also had to change the swagger_model.py processor so it can handle the type discriminator and subtyping. I took that a big step forward, and using that information to generate an ari_model module, which can validate a JSON object against the Swagger model. The REST and WebSocket generators were changed to take advantage of the validators. If compiled with AST_DEVMODE enabled, JSON objects that don't match their corresponding models will not be sent out. For REST API calls, a 500 Internal Server response is sent. For WebSockets, the invalid JSON message is replaced with an error message. Since this took over about half of the job of the existing JSON generators, and the .to_json virtual function on messages took over the other half, I reluctantly removed the generators. The validators turned up all sorts of errors and inconsistencies in our data models, and the code. These were cleaned up, with checks in the code generator avoid some of the consistency problems in the future. * The model for a channel snapshot was trimmed down to match the information sent via AMI. Many of the field being sent were not useful in the general case. * The model for a bridge snapshot was updated to be more consistent with the other ARI models. Another impact of introducing subtyping was that the swagger-codegen documentation generator was insufficient (at least until it catches up with Swagger 1.2). I wanted it to be easier to generate docs for the API anyways, so I ported the wiki pages to use the Asterisk Swagger generator. In the process, I was able to clean up many of the model links, which would occasionally give inconsistent results on the wiki. I also added error responses to the wiki docs, making the wiki documentation more complete. Finally, since Stasis-HTTP will now be named Asterisk REST Interface (ARI), any new functions and files I created carry the ari_ prefix. I changed a few stasis_http references to ari where it was non-intrusive and made sense. (closes issue ASTERISK-21885) Review: https://reviewboard.asterisk.org/r/2639/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@393529 65c4cc65-6c06-0410-ace0-fbb531ad65f3	13 years ago
David M. Lee	dcf03554a0	Shuffle RESTful URL's around. ... This patch moves the RESTful URL's around to more appropriate locations for release. The /stasis URL's are moved to /ari, since Asterisk REST Interface was a more appropriate name than Stasis-HTTP. (Most of the code still has stasis_http references, but they will be cleaned up after there are no more outstanding branches that would have merge conflicts with such a change). A larger change was moving the ARI events WebSocket off of the shared /ws URL to its permanent home on /ari/events. The Swagger code generator was extended to handle "upgrade: websocket" and "websocketProtocol:" attributes on an operation. The WebSocket module was modified to better handle WebSocket servers that have a single registered protocol handler. If a client connections does not specify the Sec-WebSocket-Protocol header, and the server has a single protocol handler registered, the WebSocket server will go ahead and accept the client for that subprotocol. (closes issue ASTERISK-21857) Review: https://reviewboard.asterisk.org/r/2621/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@393528 65c4cc65-6c06-0410-ace0-fbb531ad65f3	13 years ago
Kinsey Moore	7ce05bfb9b	Add channel events for res_stasis apps ... This change adds a framework in res_stasis for handling events from channel topics. JSON event generation and validation code is created from event documentation in rest-api/api-docs/events.json to assist in JSON event generation, ensure consistency, and ensure that accurate documentation is available for ALL events that are received by res_stasis applications. The userevent application has been refactored along with the code that handles userevent channel blob events to pass the headers as key/value pairs in the JSON blob. As a side-effect, app_userevent now handles duplicate keys by overwriting the previous value. Review: https://reviewboard.asterisk.org/r/2428/ (closes issue ASTERISK-21180) Patch-By: Kinsey Moore <kmoore@digium.com> git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@388275 65c4cc65-6c06-0410-ace0-fbb531ad65f3	13 years ago
Kinsey Moore	5eb184aa95	Fix spelling error in python doc ... git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@386774 65c4cc65-6c06-0410-ace0-fbb531ad65f3	13 years ago
David M. Lee	22aa2a6e9b	Oops. Mustache doesn't like dictionaries ... git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@386461 65c4cc65-6c06-0410-ace0-fbb531ad65f3	13 years ago
David M. Lee	1c21b8575b	This patch adds a RESTful HTTP interface to Asterisk. ... The API itself is documented using Swagger, a lightweight mechanism for documenting RESTful API's using JSON. This allows us to use swagger-ui to provide executable documentation for the API, generate client bindings in different languages, and generate a lot of the boilerplate code for implementing the RESTful bindings. The API docs live in the rest-api/ directory. The RESTful bindings are generated from the Swagger API docs using a set of Mustache templates. The code generator is written in Python, and uses Pystache. Pystache has no dependencies, and be installed easily using pip. Code generation code lives in rest-api-templates/. The generated code reduces a lot of boilerplate when it comes to handling HTTP requests. It also helps us have greater consistency in the REST API. (closes issue ASTERISK-20891) Review: https://reviewboard.asterisk.org/r/2376/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@386232 65c4cc65-6c06-0410-ace0-fbb531ad65f3	13 years ago