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.
This commit is contained in:
parent
248b0637ff
commit
812156edfd
3
Makefile
3
Makefile
|
@ -1118,7 +1118,8 @@ ifeq ($(PYTHON),:)
|
||||||
else
|
else
|
||||||
@$(INSTALL) -d doc/rest-api
|
@$(INSTALL) -d doc/rest-api
|
||||||
$(PYTHON) rest-api-templates/make_ari_stubs.py \
|
$(PYTHON) rest-api-templates/make_ari_stubs.py \
|
||||||
rest-api/resources.json .
|
--resources rest-api/resources.json --source-dir $(ASTTOPDIR) \
|
||||||
|
--dest-dir $(ASTTOPDIR)/doc/rest-api --docs-prefix ../
|
||||||
endif
|
endif
|
||||||
|
|
||||||
check-alembic: makeopts
|
check-alembic: makeopts
|
||||||
|
|
|
@ -1,73 +1,75 @@
|
||||||
{{#api_declaration}}
|
{{#api_declaration}}
|
||||||
h1. {{name_title}}
|
# {{name_title}}
|
||||||
|
|
||||||
|| Method || Path<br>h5. Parameters are case-sensitive || Return Model || Summary ||
|
|
||||||
|
|
||||||
|
| Method | Path (Parameters are case-sensitive) | Return Model | Summary |
|
||||||
|
|:------ |:------------------------------------ |:------------ |:------- |
|
||||||
{{#apis}}
|
{{#apis}}
|
||||||
{{#operations}}
|
{{#operations}}
|
||||||
| {{http_method}} | [{{wiki_path}}|#{{nickname}}] | {{#response_class}}{{#is_primitive}}{{name}}{{/is_primitive}}{{^is_primitive}}[{{wiki_name}}|{{wiki_prefix}} REST Data Models#{{singular_name}}]{{/is_primitive}}{{/response_class}} | {{{summary}}} |
|
| {{http_method}} | [{{wiki_path}}](#{{nickname}}) | {{#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}}} |
|
||||||
{{/operations}}
|
{{/operations}}
|
||||||
{{/apis}}
|
{{/apis}}
|
||||||
{{#apis}}
|
{{#apis}}
|
||||||
{{#operations}}
|
{{#operations}}
|
||||||
|
|
||||||
{anchor:{{nickname}}}
|
---
|
||||||
h2. {{nickname}}: {{http_method}} {{wiki_path}}
|
[//]: # (anchor:{{nickname}})
|
||||||
|
## {{nickname}}
|
||||||
|
### {{http_method}} {{wiki_path}}
|
||||||
{{{wiki_summary}}}{{#wiki_notes}} {{{wiki_notes}}}{{/wiki_notes}}
|
{{{wiki_summary}}}{{#wiki_notes}} {{{wiki_notes}}}{{/wiki_notes}}
|
||||||
{{#has_path_parameters}}
|
{{#has_path_parameters}}
|
||||||
|
|
||||||
h3. Path parameters
|
### Path parameters
|
||||||
Parameters are case-sensitive.
|
Parameters are case-sensitive.
|
||||||
{{#path_parameters}}
|
{{#path_parameters}}
|
||||||
* {{name}}: _{{data_type}}_ - {{{wiki_description}}}
|
* {{name}}: _{{data_type}}_ - {{{wiki_description}}}
|
||||||
{{#default_value}}
|
{{#default_value}}
|
||||||
** Default: {{default_value}}
|
* Default: {{default_value}}
|
||||||
{{/default_value}}
|
{{/default_value}}
|
||||||
{{#wiki_allowable_values}}
|
{{#wiki_allowable_values}}
|
||||||
** {{wiki_allowable_values}}
|
* {{wiki_allowable_values}}
|
||||||
{{/wiki_allowable_values}}
|
{{/wiki_allowable_values}}
|
||||||
{{/path_parameters}}
|
{{/path_parameters}}
|
||||||
{{/has_path_parameters}}
|
{{/has_path_parameters}}
|
||||||
{{#has_query_parameters}}
|
{{#has_query_parameters}}
|
||||||
|
|
||||||
h3. Query parameters
|
### Query parameters
|
||||||
{{#query_parameters}}
|
{{#query_parameters}}
|
||||||
* {{name}}: _{{data_type}}_ -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
|
* {{name}}: _{{data_type}}_ -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
|
||||||
{{#default_value}}
|
{{#default_value}}
|
||||||
** Default: {{default_value}}
|
* Default: {{default_value}}
|
||||||
{{/default_value}}
|
{{/default_value}}
|
||||||
{{#wiki_allowable_values}}
|
{{#wiki_allowable_values}}
|
||||||
** {{wiki_allowable_values}}
|
* {{wiki_allowable_values}}
|
||||||
{{/wiki_allowable_values}}
|
{{/wiki_allowable_values}}
|
||||||
{{#allow_multiple}}
|
{{#allow_multiple}}
|
||||||
** Allows comma separated values.
|
* Allows comma separated values.
|
||||||
{{/allow_multiple}}
|
{{/allow_multiple}}
|
||||||
{{/query_parameters}}
|
{{/query_parameters}}
|
||||||
{{/has_query_parameters}}
|
{{/has_query_parameters}}
|
||||||
{{#has_body_parameter}}
|
{{#has_body_parameter}}
|
||||||
|
|
||||||
h3. Body parameter
|
|
||||||
|
### Body parameter
|
||||||
{{#body_parameter}}
|
{{#body_parameter}}
|
||||||
* {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
|
* {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
|
||||||
{{#allow_multiple}}
|
{{#allow_multiple}}
|
||||||
** Allows comma separated values.
|
* Allows comma separated values.
|
||||||
{{/allow_multiple}}
|
{{/allow_multiple}}
|
||||||
{{/body_parameter}}
|
{{/body_parameter}}
|
||||||
{{/has_body_parameter}}
|
{{/has_body_parameter}}
|
||||||
{{#has_header_parameters}}
|
{{#has_header_parameters}}
|
||||||
|
|
||||||
h3. Header parameters
|
### Header parameters
|
||||||
{{#header_parameters}}
|
{{#header_parameters}}
|
||||||
* {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
|
* {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
|
||||||
{{#allow_multiple}}
|
{{#allow_multiple}}
|
||||||
** Allows comma separated values.
|
* Allows comma separated values.
|
||||||
{{/allow_multiple}}
|
{{/allow_multiple}}
|
||||||
{{/header_parameters}}
|
{{/header_parameters}}
|
||||||
{{/has_header_parameters}}
|
{{/has_header_parameters}}
|
||||||
{{#has_error_responses}}
|
{{#has_error_responses}}
|
||||||
|
|
||||||
h3. Error Responses
|
### Error Responses
|
||||||
{{#error_responses}}
|
{{#error_responses}}
|
||||||
* {{code}} - {{{wiki_reason}}}
|
* {{code}} - {{{wiki_reason}}}
|
||||||
{{/error_responses}}
|
{{/error_responses}}
|
||||||
|
|
|
@ -28,7 +28,7 @@ except ImportError:
|
||||||
import os.path
|
import os.path
|
||||||
|
|
||||||
from asterisk_processor import AsteriskProcessor
|
from asterisk_processor import AsteriskProcessor
|
||||||
from optparse import OptionParser
|
from argparse import ArgumentParser as ArgParser
|
||||||
from swagger_model import ResourceListing
|
from swagger_model import ResourceListing
|
||||||
from transform import Transform
|
from transform import Transform
|
||||||
|
|
||||||
|
@ -42,55 +42,61 @@ def rel(file):
|
||||||
"""
|
"""
|
||||||
return os.path.join(TOPDIR, file)
|
return os.path.join(TOPDIR, file)
|
||||||
|
|
||||||
WIKI_PREFIX = 'Asterisk 18'
|
|
||||||
|
|
||||||
API_TRANSFORMS = [
|
|
||||||
Transform(rel('api.wiki.mustache'),
|
|
||||||
'doc/rest-api/%s {{name_title}} REST API.wiki' % WIKI_PREFIX),
|
|
||||||
Transform(rel('res_ari_resource.c.mustache'),
|
|
||||||
'res/res_ari_{{c_name}}.c'),
|
|
||||||
Transform(rel('ari_resource.h.mustache'),
|
|
||||||
'res/ari/resource_{{c_name}}.h'),
|
|
||||||
Transform(rel('ari_resource.c.mustache'),
|
|
||||||
'res/ari/resource_{{c_name}}.c', overwrite=False),
|
|
||||||
]
|
|
||||||
|
|
||||||
RESOURCES_TRANSFORMS = [
|
|
||||||
Transform(rel('models.wiki.mustache'),
|
|
||||||
'doc/rest-api/%s REST Data Models.wiki' % WIKI_PREFIX),
|
|
||||||
Transform(rel('ari.make.mustache'), 'res/ari.make'),
|
|
||||||
Transform(rel('ari_model_validators.h.mustache'),
|
|
||||||
'res/ari/ari_model_validators.h'),
|
|
||||||
Transform(rel('ari_model_validators.c.mustache'),
|
|
||||||
'res/ari/ari_model_validators.c'),
|
|
||||||
]
|
|
||||||
|
|
||||||
|
|
||||||
def main(argv):
|
def main(argv):
|
||||||
parser = OptionParser(usage="Usage %prog [resources.json] [destdir]")
|
description = (
|
||||||
|
'Command line utility to export ARI documentation to markdown'
|
||||||
|
)
|
||||||
|
|
||||||
(options, args) = parser.parse_args(argv)
|
parser = ArgParser(description=description)
|
||||||
|
parser.add_argument('--resources', type=str, default="rest-api/resources.json",
|
||||||
|
help="resources.json file to process", required=False)
|
||||||
|
parser.add_argument('--source-dir', type=str, default=".",
|
||||||
|
help="Asterisk source directory", required=False)
|
||||||
|
parser.add_argument('--dest-dir', type=str, default="doc/rest-api",
|
||||||
|
help="Destination directory", required=False)
|
||||||
|
parser.add_argument('--docs-prefix', type=str, default="../",
|
||||||
|
help="Prefix to apply to links", required=False)
|
||||||
|
|
||||||
if len(args) != 3:
|
args = parser.parse_args()
|
||||||
parser.error("Wrong number of arguments")
|
if not args:
|
||||||
|
return
|
||||||
|
|
||||||
source = args[1]
|
|
||||||
dest_dir = args[2]
|
|
||||||
renderer = pystache.Renderer(search_dirs=[TOPDIR], missing_tags='strict')
|
renderer = pystache.Renderer(search_dirs=[TOPDIR], missing_tags='strict')
|
||||||
processor = AsteriskProcessor(wiki_prefix=WIKI_PREFIX)
|
processor = AsteriskProcessor(wiki_prefix=args.docs_prefix)
|
||||||
|
|
||||||
|
API_TRANSFORMS = [
|
||||||
|
Transform(rel('api.wiki.mustache'),
|
||||||
|
'%s/{{name_title}}_REST_API.md' % args.dest_dir),
|
||||||
|
Transform(rel('res_ari_resource.c.mustache'),
|
||||||
|
'res/res_ari_{{c_name}}.c'),
|
||||||
|
Transform(rel('ari_resource.h.mustache'),
|
||||||
|
'res/ari/resource_{{c_name}}.h'),
|
||||||
|
Transform(rel('ari_resource.c.mustache'),
|
||||||
|
'res/ari/resource_{{c_name}}.c', overwrite=False),
|
||||||
|
]
|
||||||
|
|
||||||
|
RESOURCES_TRANSFORMS = [
|
||||||
|
Transform(rel('models.wiki.mustache'),
|
||||||
|
'%s/_Asterisk_REST_Data_Models.md' % args.dest_dir),
|
||||||
|
Transform(rel('ari.make.mustache'), 'res/ari.make'),
|
||||||
|
Transform(rel('ari_model_validators.h.mustache'),
|
||||||
|
'res/ari/ari_model_validators.h'),
|
||||||
|
Transform(rel('ari_model_validators.c.mustache'),
|
||||||
|
'res/ari/ari_model_validators.c'),
|
||||||
|
]
|
||||||
|
|
||||||
# Build the models
|
# Build the models
|
||||||
base_dir = os.path.dirname(source)
|
base_dir = os.path.dirname(args.resources)
|
||||||
resources = ResourceListing().load_file(source, processor)
|
resources = ResourceListing().load_file(args.resources, processor)
|
||||||
for api in resources.apis:
|
for api in resources.apis:
|
||||||
api.load_api_declaration(base_dir, processor)
|
api.load_api_declaration(base_dir, processor)
|
||||||
|
|
||||||
# Render the templates
|
# Render the templates
|
||||||
for api in resources.apis:
|
for api in resources.apis:
|
||||||
for transform in API_TRANSFORMS:
|
for transform in API_TRANSFORMS:
|
||||||
transform.render(renderer, api, dest_dir)
|
transform.render(renderer, api, args.source_dir)
|
||||||
for transform in RESOURCES_TRANSFORMS:
|
for transform in RESOURCES_TRANSFORMS:
|
||||||
transform.render(renderer, resources, dest_dir)
|
transform.render(renderer, resources, args.source_dir)
|
||||||
|
|
||||||
if __name__ == "__main__":
|
if __name__ == "__main__":
|
||||||
sys.exit(main(sys.argv) or 0)
|
sys.exit(main(sys.argv) or 0)
|
||||||
|
|
|
@ -1,18 +1,18 @@
|
||||||
{toc}
|
---
|
||||||
|
title: Asterisk REST Data Models
|
||||||
|
---
|
||||||
|
# Asterisk REST Data Models
|
||||||
{{#apis}}
|
{{#apis}}
|
||||||
{{#api_declaration}}
|
{{#api_declaration}}
|
||||||
{{#models}}
|
{{#models}}
|
||||||
h1. {{id}}
|
## {{id}}
|
||||||
{{#extends}}Base type: [{{extends}}|#{{extends}}]{{/extends}}
|
{{#extends}}Base type: [{{extends}}](#{{extends}}){{/extends}}
|
||||||
{{#has_subtypes}}Subtypes:{{#all_subtypes}} [{{id}}|#{{id}}]{{/all_subtypes}}{{/has_subtypes}}
|
{{#has_subtypes}}Subtypes:{{#all_subtypes}} [{{id}}](#{{id}}){{/all_subtypes}}{{/has_subtypes}}
|
||||||
{{#wiki_description}}
|
### Model
|
||||||
|
``` javascript title="{{id}}" linenums="1"
|
||||||
{{{wiki_description}}}
|
|
||||||
{{/wiki_description}}
|
|
||||||
{code:language=javascript|collapse=true}
|
|
||||||
{{{model_json}}}
|
{{{model_json}}}
|
||||||
{code}
|
```
|
||||||
|
### Properties
|
||||||
{{#properties}}
|
{{#properties}}
|
||||||
* {{name}}: {{#type}}{{#is_primitive}}{{wiki_name}}{{/is_primitive}}{{^is_primitive}}[{{wiki_name}}|#{{singular_name}}]{{/is_primitive}}{{/type}}{{^required}} _(optional)_{{/required}}{{#wiki_description}} - {{{wiki_description}}}{{/wiki_description}}
|
* {{name}}: {{#type}}{{#is_primitive}}{{wiki_name}}{{/is_primitive}}{{^is_primitive}}[{{wiki_name}}|#{{singular_name}}]{{/is_primitive}}{{/type}}{{^required}} _(optional)_{{/required}}{{#wiki_description}} - {{{wiki_description}}}{{/wiki_description}}
|
||||||
{{/properties}}
|
{{/properties}}
|
||||||
|
|
|
@ -332,6 +332,7 @@ class SwaggerType(Stringify):
|
||||||
self.is_discriminator = None
|
self.is_discriminator = None
|
||||||
self.is_list = None
|
self.is_list = None
|
||||||
self.singular_name = None
|
self.singular_name = None
|
||||||
|
self.lc_singular_name = None
|
||||||
self.is_primitive = None
|
self.is_primitive = None
|
||||||
self.is_binary = None
|
self.is_binary = None
|
||||||
|
|
||||||
|
@ -345,8 +346,10 @@ class SwaggerType(Stringify):
|
||||||
self.is_list = type_param is not None
|
self.is_list = type_param is not None
|
||||||
if self.is_list:
|
if self.is_list:
|
||||||
self.singular_name = type_param
|
self.singular_name = type_param
|
||||||
|
self.lc_singular_name = type_param.lower()
|
||||||
else:
|
else:
|
||||||
self.singular_name = self.name
|
self.singular_name = self.name
|
||||||
|
self.lc_singular_name = self.name.lower()
|
||||||
self.is_primitive = self.singular_name in SWAGGER_PRIMITIVES
|
self.is_primitive = self.singular_name in SWAGGER_PRIMITIVES
|
||||||
self.is_binary = (self.singular_name == 'binary')
|
self.is_binary = (self.singular_name == 'binary')
|
||||||
processor.process_type(self, context)
|
processor.process_type(self, context)
|
||||||
|
|
Loading…
Reference in New Issue