def render_table(self, return_values: Dict[str, Any],
spacing: int) -> List[str]:
IGNORE = ["result", "msg"]
ans = []
for return_value in return_values:
if return_value in IGNORE:
continue
description = return_values[return_value]['description']
# Test to make sure deprecated keys are marked appropriately.
if likely_deprecated_parameter(description):
assert (return_values[return_value]['deprecated'])
ans.append(self.render_desc(description, spacing, return_value))
if 'properties' in return_values[return_value]:
ans += self.render_table(
return_values[return_value]['properties'], spacing + 4)
if return_values[return_value].get('additionalProperties', False):
ans.append(
self.render_desc(
return_values[return_value]['additionalProperties']
['description'], spacing + 4))
if 'properties' in return_values[return_value][
'additionalProperties']:
ans += self.render_table(
return_values[return_value]['additionalProperties']
['properties'], spacing + 8)
if ('items' in return_values[return_value]
and 'properties' in return_values[return_value]['items']):
ans += self.render_table(
return_values[return_value]['items']['properties'],
spacing + 4)
return ans
def render_table(self, return_values: Dict[str, Any],
spacing: int) -> List[str]:
IGNORE = ["result", "msg"]
ans = []
for return_value in return_values:
if return_value in IGNORE:
continue
if 'oneOf' in return_values[return_value]:
# For elements using oneOf there are two descriptions. The first description
# should be at level with the oneOf and should contain the basic non-specific
# description of the endpoint. Then for each element of oneOf there is a
# specialized description for that particular case. The description used
# right below is the main description.
ans.append(
self.render_desc(
return_values[return_value]['description'], spacing,
return_value))
for element in return_values[return_value]['oneOf']:
if 'description' not in element:
continue
# Add the specialized description of the oneOf element.
ans.append(
self.render_desc(element['description'], spacing + 4))
# If the oneOf element is an object schema then render the documentation
# of its keys.
if 'properties' in element:
ans += self.render_table(element['properties'],
spacing + 8)
continue
description = return_values[return_value]['description']
# Test to make sure deprecated keys are marked appropriately.
if likely_deprecated_parameter(description):
assert (return_values[return_value]['deprecated'])
ans.append(self.render_desc(description, spacing, return_value))
if 'properties' in return_values[return_value]:
ans += self.render_table(
return_values[return_value]['properties'], spacing + 4)
if return_values[return_value].get('additionalProperties', False):
ans.append(
self.render_desc(
return_values[return_value]['additionalProperties']
['description'], spacing + 4))
if 'properties' in return_values[return_value][
'additionalProperties']:
ans += self.render_table(
return_values[return_value]['additionalProperties']
['properties'], spacing + 8)
if ('items' in return_values[return_value]
and 'properties' in return_values[return_value]['items']):
ans += self.render_table(
return_values[return_value]['items']['properties'],
spacing + 4)
return ans
def render_table(self, arguments: Sequence[Mapping[str, Any]]) -> List[str]:
# TODO: Fix naming now that this no longer renders a table.
table = []
argument_template = """
<div class="api-argument">
<p class="api-argument-name"><strong>{argument}</strong> {required} {deprecated}</p>
<div class="api-example">
<span class="api-argument-example-label">Example</span>: <code>{example}</code>
</div>
<div class="api-description">{description}</div>
<hr>
</div>"""
md_engine = markdown.Markdown(extensions=[])
arguments = sorted(arguments, key=lambda argument: 'deprecated' in argument)
for argument in arguments:
description = argument['description']
oneof = ['`' + str(item) + '`'
for item in argument.get('schema', {}).get('enum', [])]
if oneof:
description += '\nMust be one of: {}.'.format(', '.join(oneof))
default = argument.get('schema', {}).get('default')
if default is not None:
description += f'\nDefaults to `{json.dumps(default)}`.'
# TODO: OpenAPI allows indicating where the argument goes
# (path, querystring, form data...). We should document this detail.
example = ""
if 'example' in argument:
example = argument['example']
else:
example = json.dumps(argument['content']['application/json']['example'])
required_string: str = "required"
if argument.get('in', '') == 'path':
# Any path variable is required
assert argument['required']
required_string = 'required in path'
if argument.get('required', False):
required_block = f'<span class="api-argument-required">{required_string}</span>'
else:
required_block = '<span class="api-argument-optional">optional</span>'
# Test to make sure deprecated parameters are marked so.
if likely_deprecated_parameter(description):
assert(argument['deprecated'])
if argument.get('deprecated', False):
deprecated_block = '<span class="api-argument-deprecated">Deprecated</span>'
else:
deprecated_block = ''
table.append(argument_template.format(
argument=argument.get('argument') or argument.get('name'),
example=escape_html(example),
required=required_block,
deprecated=deprecated_block,
description=md_engine.convert(description),
))
return table
def render_table(self, arguments: Sequence[Mapping[str,
Any]]) -> List[str]:
# TODO: Fix naming now that this no longer renders a table.
table = []
argument_template = """
<div class="api-argument" id="parameter-{argument}">
<p class="api-argument-name"><strong>{argument}</strong> <span class="api-field-type">{type}</span> {required} {deprecated} <a href="#parameter-{argument}" class="api-argument-hover-link"><i class="fa fa-chain"></i></a></p>
<div class="api-example">
<span class="api-argument-example-label">Example</span>: <code>{example}</code>
</div>
<div class="api-description">{description}</div>
<hr>
</div>"""
md_engine = markdown.Markdown(extensions=[])
arguments = sorted(arguments,
key=lambda argument: "deprecated" in argument)
for argument in arguments:
description = argument["description"]
oneof = [
"`" + str(item) + "`"
for item in argument.get("schema", {}).get("enum", [])
]
if oneof:
description += "\nMust be one of: {}.".format(", ".join(oneof))
default = argument.get("schema", {}).get("default")
if default is not None:
description += f"\nDefaults to `{json.dumps(default)}`."
data_type = ""
if "schema" in argument:
data_type = generate_data_type(argument["schema"])
else:
data_type = generate_data_type(
argument["content"]["application/json"]["schema"])
# TODO: OpenAPI allows indicating where the argument goes
# (path, querystring, form data...). We should document this detail.
example = ""
if "example" in argument:
example = argument["example"]
else:
example = json.dumps(
argument["content"]["application/json"]["example"])
required_string: str = "required"
if argument.get("in", "") == "path":
# Any path variable is required
assert argument["required"]
required_string = "required in path"
if argument.get("required", False):
required_block = f'<span class="api-argument-required">{required_string}</span>'
else:
required_block = '<span class="api-argument-optional">optional</span>'
# Test to make sure deprecated parameters are marked so.
if likely_deprecated_parameter(description):
assert argument["deprecated"]
if argument.get("deprecated", False):
deprecated_block = '<span class="api-argument-deprecated">Deprecated</span>'
else:
deprecated_block = ""
table.append(
argument_template.format(
argument=argument.get("argument") or argument.get("name"),
example=escape_html(example),
required=required_block,
deprecated=deprecated_block,
description=md_engine.convert(description),
type=data_type,
))
return table
def render_table(self, return_values: Dict[str, Any],
spacing: int) -> List[str]:
IGNORE = ["result", "msg"]
ans = []
for return_value in return_values:
if return_value in IGNORE:
continue
if "oneOf" in return_values[return_value]:
# For elements using oneOf there are two descriptions. The first description
# should be at level with the oneOf and should contain the basic non-specific
# description of the endpoint. Then for each element of oneOf there is a
# specialized description for that particular case. The description used
# right below is the main description.
data_type = generate_data_type(return_values[return_value])
ans.append(
self.render_desc(
return_values[return_value]["description"], spacing,
data_type, return_value))
for element in return_values[return_value]["oneOf"]:
if "description" not in element:
continue
# Add the specialized description of the oneOf element.
data_type = generate_data_type(element)
ans.append(
self.render_desc(element["description"], spacing + 4,
data_type))
# If the oneOf element is an object schema then render the documentation
# of its keys.
if "properties" in element:
ans += self.render_table(element["properties"],
spacing + 8)
continue
description = return_values[return_value]["description"]
data_type = generate_data_type(return_values[return_value])
# Test to make sure deprecated keys are marked appropriately.
if likely_deprecated_parameter(description):
assert return_values[return_value]["deprecated"]
ans.append(
self.render_desc(description, spacing, data_type,
return_value))
if "properties" in return_values[return_value]:
ans += self.render_table(
return_values[return_value]["properties"], spacing + 4)
if return_values[return_value].get("additionalProperties", False):
data_type = generate_data_type(
return_values[return_value]["additionalProperties"])
ans.append(
self.render_desc(
return_values[return_value]["additionalProperties"]
["description"],
spacing + 4,
data_type,
))
if "properties" in return_values[return_value][
"additionalProperties"]:
ans += self.render_table(
return_values[return_value]["additionalProperties"]
["properties"],
spacing + 8,
)
if ("items" in return_values[return_value]
and "properties" in return_values[return_value]["items"]):
ans += self.render_table(
return_values[return_value]["items"]["properties"],
spacing + 4)
return ans
