diff --git a/Makefile b/Makefile index 3da2039828..546a316c4d 100644 --- a/Makefile +++ b/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 diff --git a/rest-api-templates/api.wiki.mustache b/rest-api-templates/api.wiki.mustache index a51c3e6ce6..343aa11b5c 100644 --- a/rest-api-templates/api.wiki.mustache +++ b/rest-api-templates/api.wiki.mustache @@ -1,73 +1,75 @@ {{#api_declaration}} -h1. {{name_title}} - -|| Method || Path
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}} diff --git a/rest-api-templates/make_ari_stubs.py b/rest-api-templates/make_ari_stubs.py index 9a340d3fb2..a6c6a24527 100755 --- a/rest-api-templates/make_ari_stubs.py +++ b/rest-api-templates/make_ari_stubs.py @@ -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 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): - parser = OptionParser(usage="Usage %prog [resources.json] [destdir]") - - (options, args) = parser.parse_args(argv) - - if len(args) != 3: - parser.error("Wrong number of arguments") + description = ( + 'Command line utility to export ARI documentation to markdown' + ) + + 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) + + 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) diff --git a/rest-api-templates/models.wiki.mustache b/rest-api-templates/models.wiki.mustache index 2bc1e467f1..fe70f08595 100644 --- a/rest-api-templates/models.wiki.mustache +++ b/rest-api-templates/models.wiki.mustache @@ -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}} diff --git a/rest-api-templates/swagger_model.py b/rest-api-templates/swagger_model.py index 50c5fb07b3..57bce0cbfa 100644 --- a/rest-api-templates/swagger_model.py +++ b/rest-api-templates/swagger_model.py @@ -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)