mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-02 19:16:15 +00:00
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 d5e7988df4
)
This commit is contained in:
committed by
Asterisk Development Team
parent
82c1fb71e6
commit
a21971cfeb
@@ -1,11 +1,14 @@
|
||||
{{#api_declaration}}
|
||||
# {{name_title}}
|
||||
{{#since}}
|
||||
## Since: {{since}}
|
||||
{{/since}}
|
||||
|
||||
| Method | Path (Parameters are case-sensitive) | Return Model | Summary |
|
||||
|:------ |:------------------------------------ |:------------ |:------- |
|
||||
| Method | Path (Parameters are case-sensitive) | Return Model | Summary | Since |
|
||||
|:------ |:------------------------------------ |:------------ |:------- |:----- |
|
||||
{{#apis}}
|
||||
{{#operations}}
|
||||
| {{http_method}} | [{{wiki_path}}](#{{nickname_lc}}) | {{#response_class}}{{#is_primitive}}{{name}}{{/is_primitive}}{{^is_primitive}}[{{wiki_name}}]({{wiki_prefix}}Asterisk_REST_Data_Models#{{lc_singular_name}}){{/is_primitive}}{{/response_class}} | {{{summary}}} |
|
||||
| {{http_method}} | [{{wiki_path}}](#{{nickname_lc}}) | {{#response_class}}{{#is_primitive}}{{name}}{{/is_primitive}}{{^is_primitive}}[{{wiki_name}}]({{wiki_prefix}}Asterisk_REST_Data_Models#{{lc_singular_name}}){{/is_primitive}}{{/response_class}} | {{{summary}}} | {{since}} |
|
||||
{{/operations}}
|
||||
{{/apis}}
|
||||
{{#apis}}
|
||||
@@ -14,6 +17,9 @@
|
||||
---
|
||||
[//]: # (anchor:{{nickname_lc}})
|
||||
## {{nickname}}
|
||||
{{#since}}
|
||||
### Since: {{since}}
|
||||
{{/since}}
|
||||
### {{http_method}} {{wiki_path}}
|
||||
{{{wiki_summary}}}{{#wiki_notes}} {{{wiki_notes}}}{{/wiki_notes}}
|
||||
{{#has_path_parameters}}
|
||||
|
@@ -373,6 +373,7 @@ class Operation(Stringify):
|
||||
self.summary = None
|
||||
self.notes = None
|
||||
self.error_responses = []
|
||||
self.since = []
|
||||
|
||||
def load(self, op_json, processor, context):
|
||||
context = context.next_stack(op_json, 'nickname')
|
||||
@@ -383,6 +384,8 @@ class Operation(Stringify):
|
||||
response_class = op_json.get('responseClass')
|
||||
self.response_class = response_class and SwaggerType().load(
|
||||
response_class, processor, context)
|
||||
since = op_json.get('since') or []
|
||||
self.since = ", ".join(since)
|
||||
|
||||
# Specifying WebSocket URL's is our own extension
|
||||
self.is_websocket = op_json.get('upgrade') == 'websocket'
|
||||
@@ -611,6 +614,7 @@ class ApiDeclaration(Stringify):
|
||||
self.api_version = None
|
||||
self.base_path = None
|
||||
self.resource_path = None
|
||||
self.since = []
|
||||
self.apis = []
|
||||
self.models = []
|
||||
|
||||
@@ -658,6 +662,8 @@ class ApiDeclaration(Stringify):
|
||||
self.base_path = api_decl_json.get('basePath')
|
||||
self.resource_path = api_decl_json.get('resourcePath')
|
||||
self.requires_modules = api_decl_json.get('requiresModules') or []
|
||||
since = api_decl_json.get('since') or []
|
||||
self.since = ", ".join(since)
|
||||
api_json = api_decl_json.get('apis') or []
|
||||
self.apis = [
|
||||
Api().load(j, processor, context) for j in api_json]
|
||||
|
Reference in New Issue
Block a user