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:
George Joseph
parent
afdce6fc53
commit
c3af86ae10
3
Makefile
3
Makefile
|
|
@ -1118,7 +1118,8 @@ ifeq ($(PYTHON),:)
|
|||
else
|
||||
@$(INSTALL) -d doc/rest-api
|
||||
$(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
|
||||
|
||||
check-alembic: makeopts
|
||||
|
|
|
|||
|
|
@ -1,73 +1,75 @@
|
|||
{{#api_declaration}}
|
||||
h1. {{name_title}}
|
||||
|
||||
|| Method || Path<br>h5. Parameters are case-sensitive || Return Model || Summary ||
|
||||
# {{name_title}}
|
||||
|
||||
| Method | Path (Parameters are case-sensitive) | Return Model | Summary |
|
||||
|:------ |:------------------------------------ |:------------ |:------- |
|
||||
{{#apis}}
|
||||
{{#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}}
|
||||
{{/apis}}
|
||||
{{#apis}}
|
||||
{{#operations}}
|
||||
|
||||
{anchor:{{nickname}}}
|
||||
h2. {{nickname}}: {{http_method}} {{wiki_path}}
|
||||
|
||||
---
|
||||
[//]: # (anchor:{{nickname}})
|
||||
## {{nickname}}
|
||||
### {{http_method}} {{wiki_path}}
|
||||
{{{wiki_summary}}}{{#wiki_notes}} {{{wiki_notes}}}{{/wiki_notes}}
|
||||
{{#has_path_parameters}}
|
||||
|
||||
h3. Path parameters
|
||||
### Path parameters
|
||||
Parameters are case-sensitive.
|
||||
{{#path_parameters}}
|
||||
* {{name}}: _{{data_type}}_ - {{{wiki_description}}}
|
||||
{{#default_value}}
|
||||
** Default: {{default_value}}
|
||||
* Default: {{default_value}}
|
||||
{{/default_value}}
|
||||
{{#wiki_allowable_values}}
|
||||
** {{wiki_allowable_values}}
|
||||
* {{wiki_allowable_values}}
|
||||
{{/wiki_allowable_values}}
|
||||
{{/path_parameters}}
|
||||
{{/has_path_parameters}}
|
||||
{{#has_query_parameters}}
|
||||
|
||||
h3. Query parameters
|
||||
### Query parameters
|
||||
{{#query_parameters}}
|
||||
* {{name}}: _{{data_type}}_ -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
|
||||
{{#default_value}}
|
||||
** Default: {{default_value}}
|
||||
* Default: {{default_value}}
|
||||
{{/default_value}}
|
||||
{{#wiki_allowable_values}}
|
||||
** {{wiki_allowable_values}}
|
||||
* {{wiki_allowable_values}}
|
||||
{{/wiki_allowable_values}}
|
||||
{{#allow_multiple}}
|
||||
** Allows comma separated values.
|
||||
* Allows comma separated values.
|
||||
{{/allow_multiple}}
|
||||
{{/query_parameters}}
|
||||
{{/has_query_parameters}}
|
||||
{{#has_body_parameter}}
|
||||
|
||||
h3. Body parameter
|
||||
|
||||
### Body parameter
|
||||
{{#body_parameter}}
|
||||
* {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
|
||||
{{#allow_multiple}}
|
||||
** Allows comma separated values.
|
||||
* Allows comma separated values.
|
||||
{{/allow_multiple}}
|
||||
{{/body_parameter}}
|
||||
{{/has_body_parameter}}
|
||||
{{#has_header_parameters}}
|
||||
|
||||
h3. Header parameters
|
||||
### Header parameters
|
||||
{{#header_parameters}}
|
||||
* {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
|
||||
{{#allow_multiple}}
|
||||
** Allows comma separated values.
|
||||
* Allows comma separated values.
|
||||
{{/allow_multiple}}
|
||||
{{/header_parameters}}
|
||||
{{/has_header_parameters}}
|
||||
{{#has_error_responses}}
|
||||
|
||||
h3. Error Responses
|
||||
### Error Responses
|
||||
{{#error_responses}}
|
||||
* {{code}} - {{{wiki_reason}}}
|
||||
{{/error_responses}}
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ except ImportError:
|
|||
import os.path
|
||||
|
||||
from asterisk_processor import AsteriskProcessor
|
||||
from optparse import OptionParser
|
||||
from argparse import ArgumentParser as ArgParser
|
||||
from swagger_model import ResourceListing
|
||||
from transform import Transform
|
||||
|
||||
|
|
@ -42,55 +42,61 @@ def rel(file):
|
|||
"""
|
||||
return os.path.join(TOPDIR, file)
|
||||
|
||||
WIKI_PREFIX = 'Asterisk 16'
|
||||
|
||||
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):
|
||||
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:
|
||||
parser.error("Wrong number of arguments")
|
||||
args = parser.parse_args()
|
||||
if not args:
|
||||
return
|
||||
|
||||
source = args[1]
|
||||
dest_dir = args[2]
|
||||
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
|
||||
base_dir = os.path.dirname(source)
|
||||
resources = ResourceListing().load_file(source, processor)
|
||||
base_dir = os.path.dirname(args.resources)
|
||||
resources = ResourceListing().load_file(args.resources, processor)
|
||||
for api in resources.apis:
|
||||
api.load_api_declaration(base_dir, processor)
|
||||
|
||||
# Render the templates
|
||||
for api in resources.apis:
|
||||
for transform in API_TRANSFORMS:
|
||||
transform.render(renderer, api, dest_dir)
|
||||
transform.render(renderer, api, args.source_dir)
|
||||
for transform in RESOURCES_TRANSFORMS:
|
||||
transform.render(renderer, resources, dest_dir)
|
||||
transform.render(renderer, resources, args.source_dir)
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv) or 0)
|
||||
|
|
|
|||
|
|
@ -1,18 +1,18 @@
|
|||
{toc}
|
||||
|
||||
---
|
||||
title: Asterisk REST Data Models
|
||||
---
|
||||
# Asterisk REST Data Models
|
||||
{{#apis}}
|
||||
{{#api_declaration}}
|
||||
{{#models}}
|
||||
h1. {{id}}
|
||||
{{#extends}}Base type: [{{extends}}|#{{extends}}]{{/extends}}
|
||||
{{#has_subtypes}}Subtypes:{{#all_subtypes}} [{{id}}|#{{id}}]{{/all_subtypes}}{{/has_subtypes}}
|
||||
{{#wiki_description}}
|
||||
|
||||
{{{wiki_description}}}
|
||||
{{/wiki_description}}
|
||||
{code:language=javascript|collapse=true}
|
||||
## {{id}}
|
||||
{{#extends}}Base type: [{{extends}}](#{{extends}}){{/extends}}
|
||||
{{#has_subtypes}}Subtypes:{{#all_subtypes}} [{{id}}](#{{id}}){{/all_subtypes}}{{/has_subtypes}}
|
||||
### Model
|
||||
``` javascript title="{{id}}" linenums="1"
|
||||
{{{model_json}}}
|
||||
{code}
|
||||
```
|
||||
### 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}}
|
||||
{{/properties}}
|
||||
|
|
|
|||
|
|
@ -332,6 +332,7 @@ class SwaggerType(Stringify):
|
|||
self.is_discriminator = None
|
||||
self.is_list = None
|
||||
self.singular_name = None
|
||||
self.lc_singular_name = None
|
||||
self.is_primitive = None
|
||||
self.is_binary = None
|
||||
|
||||
|
|
@ -345,8 +346,10 @@ class SwaggerType(Stringify):
|
|||
self.is_list = type_param is not None
|
||||
if self.is_list:
|
||||
self.singular_name = type_param
|
||||
self.lc_singular_name = type_param.lower()
|
||||
else:
|
||||
self.singular_name = self.name
|
||||
self.lc_singular_name = self.name.lower()
|
||||
self.is_primitive = self.singular_name in SWAGGER_PRIMITIVES
|
||||
self.is_binary = (self.singular_name == 'binary')
|
||||
processor.process_type(self, context)
|
||||
|
|
|
|||
Loading…
Reference in New Issue