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