paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-23 04:52:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

api-docs: Check for deprecated at top level of endpoint docs.

Browse Source 
Previously, we had checked that deprecated parameters and return
values had been marked as `deprecated: true` in the OpenAPI
documentation and had a description with a deprecated note.

Here we extend that check at the top level to deprecated endpoints.

The backend test that catches a failed assertion for this check
is `test_api_doc_endpoints` in zerver/tests/test_docs.py as that
test checks for a success response all pages linked the sidebar of
the API documentation.
This commit is contained in:
Lauryn Menard
2023-10-25 16:59:10 +02:00
committed by Tim Abbott
parent 94088a7709
commit f755fd1a3a
1 changed files with 9 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
zerver/openapi/openapi.py
View File

@@ -294,7 +294,10 @@ def generate_openapi_fixture(endpoint: str, method: str) -> List[str]:
def get_openapi_description(endpoint: str, method: str) -> str:
"""Fetch a description from the full spec object."""
return openapi_spec.openapi()["paths"][endpoint][method.lower()]["description"]
endpoint_documentation = openapi_spec.openapi()["paths"][endpoint][method.lower()]
endpoint_description = endpoint_documentation["description"]
check_deprecated_consistency(endpoint_documentation, endpoint_description)
return endpoint_description
def get_openapi_summary(endpoint: str, method: str) -> str:
@@ -432,19 +435,19 @@ def validate_schema(schema: Dict[str, Any]) -> None:
validate_schema(schema["additionalProperties"])
def likely_deprecated_parameter(parameter_description: str) -> bool:
if "**Changes**: Deprecated" in parameter_description:
def deprecated_note_in_description(description: str) -> bool:
if "**Changes**: Deprecated" in description:
return True
return "**Deprecated**" in parameter_description
return "**Deprecated**" in description
def check_deprecated_consistency(argument: Mapping[str, Any], description: str) -> None:
# Test to make sure deprecated parameters are marked so.
if likely_deprecated_parameter(description):
if deprecated_note_in_description(description):
assert argument["deprecated"]
if "deprecated" in argument:
assert likely_deprecated_parameter(description)
assert deprecated_note_in_description(description)
# Skip those JSON endpoints whose query parameters are different from