14 Commits (870f59e28d3930cc30fffe01bc3e660df3d9eaa7)

Author	SHA1	Message	Date
George Joseph	24c077f1fb	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. (cherry picked from commit 3e28ddce78)	9 months ago
George Joseph	e571b7c4dd	api.wiki.mustache: Fix indentation in generated markdown ... The '*' list indicator for default values and allowable values for path, query and POST parameters need to be indented 4 spaces instead of 2. Should resolve issue 38 in the documentation repo. (cherry picked from commit 443f94b438)	2 years ago
George Joseph	a0fc6c3ab0	ari-stubs: Fix more local anchor references ... Also allow CreateDocs job to be run manually with default branches. (cherry picked from commit b68006f3a1)	2 years ago
George Joseph	1108db21ef	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. (cherry picked from commit c4508accc6)	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
George Joseph	a5c0cf4922	ari: Add documentation that path parameters are case-sensitive ... Added to api.wiki.mustache so that the generated object pages have the notation in the table header as well as under each method that has path parameters. ASTERISK-25492 #close Change-Id: I36c46c6dc0c9ac350470394a999a1b19ef3fcdaf	9 years ago
Matt Jordan	b425850f8b	rest-api-templates: Wikify error code response reasons ... Error response code descriptions may contain wiki markup that need to be escaped. Without this patch, Confluence will reject the document being sent and the responsible script will raise an exception. Change-Id: I21fcb66fee7f6332381f2b99b1b0195dff215ee5	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	2d0fb7f613	ari wiki docs: add notes about allowMultiple parameters. ... This patch adds a note to any parameter that has 'allowMultiple' set in the Swagger documentation. (closes issue ASTERISK-22704) ........ Merged revisions 402367 from http://svn.asterisk.org/svn/asterisk/branches/12 git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@402368 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	9234804a3b	Multiple revisions 400508,400842-400843,400848 ... ........ r400508 | dlee | 2013-10-03 23:54:51 -0500 (Thu, 03 Oct 2013) | 1 line Corrected response class for stopPlayback ........ r400842 | dlee | 2013-10-10 14:23:24 -0500 (Thu, 10 Oct 2013) | 1 line Correct some ARI wiki rendering errors ........ r400843 | dlee | 2013-10-10 14:26:19 -0500 (Thu, 10 Oct 2013) | 1 line Updated /play resource docs. The playback of http: resources isn't implemented... yet ........ r400848 | dlee | 2013-10-11 11:18:46 -0500 (Fri, 11 Oct 2013) | 5 lines Fix a stupid copy/paste error in ARI docs. Patches: ari-doc-patch.txt uploaded by jbigelow (license 5091) ........ Merged revisions 400508,400842-400843,400848 from http://svn.asterisk.org/svn/asterisk/branches/12 git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@400852 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 years ago
David M. Lee	417230848f	Account for {} in Swagger notes ... ........ Merged revisions 397927 from http://svn.asterisk.org/svn/asterisk/branches/12 git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@397932 65c4cc65-6c06-0410-ace0-fbb531ad65f3	12 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	12 years ago