paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-04 05:53:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

api docs: Display data type of parameters in API documentation.

Browse Source 
Previously, the data type of parameters wasn't displayed in the API
Documentation, even though that OpenAPI data is carefully validated
against the implementation.  Here we add a recursive function to
render the data types visibly in the API documentation.

This only covers the request parameters; we'll want to do something
similar for response parameters in a follow-up PR.

Fixes part of #15967.
This commit is contained in:
Suyash Vardhan Mathur
2020-12-10 20:28:12 +05:30
committed by Tim Abbott
parent b1f4c98730
commit f4cf5166bb
2 changed files with 26 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
static/styles/portico/portico.css
View File

@@ -1717,6 +1717,13 @@ label.label-title {
font-size: 12px; font-size: 12px;
color: hsl(0, 50%, 60%); color: hsl(0, 50%, 60%);
} }
.api-argument-datatype {
text-transform: lowercase;
font-weight: 600;
font-size: 14px;
color: hsl(176, 46.4%, 41%);
}
} }
.desktop-redirect-box { .desktop-redirect-box {

20
zerver/lib/markdown/api_arguments_table_generator.py
View File

@@ -92,7 +92,7 @@ class APIArgumentsTablePreprocessor(Preprocessor):
table = [] table = []
argument_template = """ argument_template = """
<div class="api-argument" id="parameter-{argument}"> <div class="api-argument" id="parameter-{argument}">
<p class="api-argument-name"><strong>{argument}</strong> {required} {deprecated} <a href="#parameter-{argument}" class="api-argument-hover-link"><i class="fa fa-chain"></i></a></p> <p class="api-argument-name"><strong>{argument}</strong> <span class="api-argument-datatype">{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"> <div class="api-example">
<span class="api-argument-example-label">Example</span>: <code>{example}</code> <span class="api-argument-example-label">Example</span>: <code>{example}</code>
</div> </div>
@@ -112,6 +112,11 @@ class APIArgumentsTablePreprocessor(Preprocessor):
default = argument.get('schema', {}).get('default') default = argument.get('schema', {}).get('default')
if default is not None: if default is not None:
description += f'\nDefaults to `{json.dumps(default)}`.' 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 # TODO: OpenAPI allows indicating where the argument goes
# (path, querystring, form data...). We should document this detail. # (path, querystring, form data...). We should document this detail.
@@ -146,9 +151,22 @@ class APIArgumentsTablePreprocessor(Preprocessor):
required=required_block, required=required_block,
deprecated=deprecated_block, deprecated=deprecated_block,
description=md_engine.convert(description), description=md_engine.convert(description),
type=data_type
)) ))
return table return table
def makeExtension(*args: Any, **kwargs: str) -> MarkdownArgumentsTableGenerator: def makeExtension(*args: Any, **kwargs: str) -> MarkdownArgumentsTableGenerator:
return MarkdownArgumentsTableGenerator(kwargs) return MarkdownArgumentsTableGenerator(kwargs)
def generate_data_type(schema: Mapping[str, Any]) -> str:
data_type = ""
if 'oneOf' in schema:
for item in schema['oneOf']:
data_type = data_type + generate_data_type(item) + " | "
data_type = data_type[:-3]
elif 'items' in schema:
data_type = "(" + generate_data_type(schema['items']) + ")[]"
else:
data_type = schema['type']
return data_type