Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

api-docs: Standardize on lowercase true, false and null. 

Creates a custom linter rule for `zerver/openapi/zulip.yaml` to
only allow lowercase versions of "true", "false" and "null".

Updates existing documentation for new rules.
This commit is contained in:
Lauryn Menard 2023-05-15 11:30:00 +02:00 committed by Tim Abbott
parent 17bdf22521
commit 4fcb243769
2 changed files with 54 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
tools/linter_lib/custom_check.py
View File

@ -904,6 +904,18 @@ puppet_rules = RuleList(
], ],
) )
openapi_rules = RuleList(
langs=["yaml"],
rules=[
*whitespace_rules,
{
"pattern": "True|TRUE|False|FALSE|Null|NULL",
"include_only": {"zerver/openapi/"},
"description": "Use lowercase for true, false and null in API documentation.",
},
],
)
txt_rules = RuleList( txt_rules = RuleList(
langs=["txt", "text", "yaml", "rst", "yml"], langs=["txt", "text", "yaml", "rst", "yml"],
rules=whitespace_rules, rules=whitespace_rules,
@ -919,4 +931,5 @@ non_py_rules = [
bash_rules, bash_rules,
txt_rules, txt_rules,
puppet_rules, puppet_rules,
openapi_rules,
] ]

82
zerver/openapi/zulip.yaml
View File

@ -567,7 +567,7 @@ paths:
using the same CSS and client-side security protections using the same CSS and client-side security protections
as are used for message content. as are used for message content.
- type: object - type: object
additionalProperties: False additionalProperties: false
description: | description: |
When the Zulip display email address of a user changes, When the Zulip display email address of a user changes,
either due to the user's email address changing, or either due to the user's email address changing, or
@ -1275,8 +1275,8 @@ paths:
Whether the history of the stream is public to its subscribers. Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies Currently always true for public streams (i.e. `"invite_only": false` implies
history_public_to_subscribers=True), but clients should not make that `"history_public_to_subscribers": true`), but clients should not make that
assumption, as we may change that behavior in the future. assumption, as we may change that behavior in the future.
is_web_public: is_web_public:
type: boolean type: boolean
@ -2136,7 +2136,7 @@ paths:
description: | description: |
The ID of the user who sent the message. The ID of the user who sent the message.
Null when event is for a rendering update of the original message, Is `null` when event is for a rendering update of the original message,
such as for an [inline URL preview][inline-url-previews]. such as for an [inline URL preview][inline-url-previews].
**Changes**: As of Zulip 5.0 (feature level 114), this field **Changes**: As of Zulip 5.0 (feature level 114), this field
@ -2151,7 +2151,7 @@ paths:
This field should be used by clients to determine if the event This field should be used by clients to determine if the event
only provides a rendering update to the message content, only provides a rendering update to the message content,
such as for an [inline URL preview][inline-url-previews]. such as for an [inline URL preview][inline-url-previews].
When `True`, the event does not reflect a user-generated edit When `true`, the event does not reflect a user-generated edit
and does not modify the message history. and does not modify the message history.
**Changes**: New in Zulip 5.0 (feature level 114). Clients can **Changes**: New in Zulip 5.0 (feature level 114). Clients can
@ -3777,7 +3777,7 @@ paths:
example: example:
{ {
"id": 0, "id": 0,
"immediate": True, "immediate": true,
"server_generation": 1619334181, "server_generation": 1619334181,
"type": "restart", "type": "restart",
"zulip_feature_level": 57, "zulip_feature_level": 57,
@ -3899,7 +3899,7 @@ paths:
nullable: true nullable: true
description: | description: |
The default pygments language code to be used for a code blocks The default pygments language code to be used for a code blocks
in this organization. Null if no default has been set. in this organization. If `null`, no default has been set.
default_language: default_language:
type: string type: string
description: | description: |
@ -5039,7 +5039,7 @@ paths:
type: integer type: integer
description: | description: |
The ID of the draft to be edited. The ID of the draft to be edited.
required: True required: true
example: 2 example: 2
- name: draft - name: draft
in: query in: query
@ -5057,7 +5057,7 @@ paths:
} }
description: | description: |
A JSON-encoded object containing a replacement draft object for this ID. A JSON-encoded object containing a replacement draft object for this ID.
required: True required: true
responses: responses:
"200": "200":
$ref: "#/components/responses/SimpleSuccess" $ref: "#/components/responses/SimpleSuccess"
@ -5085,7 +5085,7 @@ paths:
type: integer type: integer
description: | description: |
The ID of the draft you want to delete. The ID of the draft you want to delete.
required: True required: true
example: 1 example: 1
responses: responses:
"200": "200":
@ -5316,7 +5316,7 @@ paths:
This is different from the unique ID that a message would have This is different from the unique ID that a message would have
after it was sent. after it was sent.
required: True required: true
example: 1 example: 1
responses: responses:
"200": "200":
@ -6147,7 +6147,7 @@ paths:
<tr> <tr>
<td><code>historical</code></td> <td><code>historical</code></td>
<td> <td>
True for messages that the user did not receive Is `true` for messages that the user did not receive
at the time they were sent but later was added to at the time they were sent but later was added to
the user's history (E.g. because they starred or the user's history (E.g. because they starred or
reacted to a message sent to a public stream reacted to a message sent to a public stream
@ -8338,8 +8338,8 @@ paths:
description: | description: |
A boolean specifying whether authorization errors (such as when the A boolean specifying whether authorization errors (such as when the
requesting user is not authorized to access a private stream) should be requesting user is not authorized to access a private stream) should be
considered fatal or not. When `True`, an authorization error is reported considered fatal or not. When `true`, an authorization error is reported
as such. When set to `False`, the response will be a 200 and any streams as such. When set to `false`, the response will be a 200 and any streams
where the request encountered an authorization error will be listed where the request encountered an authorization error will be listed
in the `unauthorized` key. in the `unauthorized` key.
schema: schema:
@ -8426,7 +8426,7 @@ paths:
} }
description: | description: |
A typical response for when the requesting user does not have access to A typical response for when the requesting user does not have access to
a private stream and `authorization_errors_fatal` is `True`: a private stream and `"authorization_errors_fatal": true`:
- allOf: - allOf:
- $ref: "#/components/schemas/AddSubscriptionsResponse" - $ref: "#/components/schemas/AddSubscriptionsResponse"
- example: - example:
@ -8439,7 +8439,7 @@ paths:
} }
description: | description: |
A typical response for when the requesting user does not have access to A typical response for when the requesting user does not have access to
a private stream and `authorization_errors_fatal` is `False`: a private stream and `"authorization_errors_fatal": false`:
patch: patch:
operationId: update-subscriptions operationId: update-subscriptions
summary: Update subscriptions summary: Update subscriptions
@ -11200,7 +11200,7 @@ paths:
The average number of messages sent to the stream in recent weeks, The average number of messages sent to the stream in recent weeks,
rounded to the nearest integer. rounded to the nearest integer.
Null means the stream was recently created and there is If `null`, the stream was recently created and there is
insufficient data to estimate the average traffic. insufficient data to estimate the average traffic.
subscribers: subscribers:
type: array type: array
@ -11346,10 +11346,10 @@ paths:
old_unreads_missing: old_unreads_missing:
type: boolean type: boolean
description: | description: |
True if this data set was truncated because the user has too many Whether this data set was truncated because the user has too many
unread messages. When truncation occurs, only the most recent unread messages. When truncation occurs, only the most recent
`MAX_UNREAD_MESSAGES` (currently 50000) messages will be considered `MAX_UNREAD_MESSAGES` (currently 50000) messages will be considered
when forming this response. When true, we recommend that clients when forming this response. When `true`, we recommend that clients
display a warning, as they are likely to produce erroneous results display a warning, as they are likely to produce erroneous results
until reloaded with the user having fewer than `MAX_UNREAD_MESSAGES` until reloaded with the user having fewer than `MAX_UNREAD_MESSAGES`
unread messages. unread messages.
@ -12844,7 +12844,7 @@ paths:
Present if `realm` is present in `fetch_event_types`. Present if `realm` is present in `fetch_event_types`.
The default pygments language code to be used for a code blocks The default pygments language code to be used for a code blocks
in this organization. Null if no default has been set. in this organization. If `null`, no default has been set.
realm_message_content_delete_limit_seconds: realm_message_content_delete_limit_seconds:
type: integer type: integer
nullable: true nullable: true
@ -13147,7 +13147,7 @@ paths:
Clients are not responsible for checking this quota; it is included Clients are not responsible for checking this quota; it is included
in the API only for display purposes. in the API only for display purposes.
Null if there is no limit. If `null`, there is no limit.
**Changes**: New in Zulip 5.0 (feature level 72). Previously, **Changes**: New in Zulip 5.0 (feature level 72). Previously,
this was called `realm_upload_quota`. this was called `realm_upload_quota`.
@ -13367,7 +13367,7 @@ paths:
The value of the `WEB_PUBLIC_STREAMS_ENABLED` Zulip server level The value of the `WEB_PUBLIC_STREAMS_ENABLED` Zulip server level
setting. A server that has disabled this setting intends to not offer [web setting. A server that has disabled this setting intends to not offer [web
public streams](/help/public-access-option) to realms it hosts. (Zulip Cloud public streams](/help/public-access-option) to realms it hosts. (Zulip Cloud
defaults to `True`; self-hosted servers default to `False`). defaults to `true`; self-hosted servers default to `false`).
Clients should use this to determine whether to offer UI for the Clients should use this to determine whether to offer UI for the
realm-level setting for enabling web-public streams realm-level setting for enabling web-public streams
@ -15206,10 +15206,10 @@ paths:
{ {
"description": "A Scandinavian country", "description": "A Scandinavian country",
"first_message_id": 1, "first_message_id": 1,
"history_public_to_subscribers": True, "history_public_to_subscribers": true,
"invite_only": False, "invite_only": false,
"is_announcement_only": False, "is_announcement_only": false,
"is_web_public": False, "is_web_public": false,
"message_retention_days": null, "message_retention_days": null,
"name": "Denmark", "name": "Denmark",
"rendered_description": "<p>A Scandinavian country</p>", "rendered_description": "<p>A Scandinavian country</p>",
@ -16425,8 +16425,8 @@ components:
description: | description: |
Whether the history of the stream is public to its subscribers. Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies Currently always true for public streams (i.e. `"invite_only": false` implies
history_public_to_subscribers=True), but clients should not make that `"history_public_to_subscribers": true`), but clients should not make that
assumption, as we may change that behavior in the future. assumption, as we may change that behavior in the future.
first_message_id: first_message_id:
type: integer type: integer
@ -16438,7 +16438,7 @@ components:
UI like the "more topics" widget that would suggest the stream UI like the "more topics" widget that would suggest the stream
has older history that can be accessed. has older history that can be accessed.
Null is used for streams with no message history. Is `null` for streams with no message history.
is_announcement_only: is_announcement_only:
type: boolean type: boolean
deprecated: true deprecated: true
@ -16490,14 +16490,14 @@ components:
type: string type: string
nullable: true nullable: true
description: | description: |
The default sending stream of the bot. Null if the bot doesn't The default sending stream of the bot. If `null`, the bot doesn't
have a default sending stream. have a default sending stream.
default_events_register_stream: default_events_register_stream:
type: string type: string
nullable: true nullable: true
description: | description: |
The default stream for which the bot receives events/register data. Null if The default stream for which the bot receives events/register data.
the bot doesn't have such a default stream. If `null`, the bot doesn't have such a default stream.
default_all_public_streams: default_all_public_streams:
type: boolean type: boolean
description: | description: |
@ -16512,7 +16512,7 @@ components:
description: | description: |
The user ID of the bot's owner. The user ID of the bot's owner.
Null if the bot has no owner. If `null`, the bot has no owner.
services: services:
type: array type: array
description: | description: |
@ -16810,13 +16810,13 @@ components:
nullable: true nullable: true
description: | description: |
The timestamp of when the export was deleted. The timestamp of when the export was deleted.
Null if it wasn't. If `null`, it wasn't deleted.
failed_timestamp: failed_timestamp:
type: number type: number
nullable: true nullable: true
description: | description: |
The timestamp of when the export failed. The timestamp of when the export failed.
Null if it didn't. If `null`, it didn't fail.
export_url: export_url:
type: string type: string
nullable: true nullable: true
@ -17057,8 +17057,8 @@ components:
description: | description: |
Whether the history of the stream is public to its subscribers. Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies Currently always true for public streams (i.e. `"invite_only": false` implies
history_public_to_subscribers=True), but clients should not make that `"history_public_to_subscribers": true`), but clients should not make that
assumption, as we may change that behavior in the future. assumption, as we may change that behavior in the future.
first_message_id: first_message_id:
type: integer type: integer
@ -17070,7 +17070,7 @@ components:
UI like the "more topics" widget that would suggest the stream UI like the "more topics" widget that would suggest the stream
has older history that can be accessed. has older history that can be accessed.
Null is used for streams with no message history. Is `null` for streams with no message history.
stream_weekly_traffic: stream_weekly_traffic:
type: integer type: integer
nullable: true nullable: true
@ -17078,7 +17078,7 @@ components:
The average number of messages sent to the stream in recent weeks, The average number of messages sent to the stream in recent weeks,
rounded to the nearest integer. rounded to the nearest integer.
Null means the stream was recently created and there is If `null`, the stream was recently created and there is
insufficient data to estimate the average traffic. insufficient data to estimate the average traffic.
can_remove_subscribers_group_id: can_remove_subscribers_group_id:
type: integer type: integer
@ -17820,7 +17820,7 @@ components:
nullable: true nullable: true
description: | description: |
URL for the user's avatar. Will be `null` if the `client_gravatar` URL for the user's avatar. Will be `null` if the `client_gravatar`
query parameter was set to `True` and the user's avatar is hosted by query parameter was set to `true` and the user's avatar is hosted by
the Gravatar provider (i.e. the user has never uploaded an avatar). the Gravatar provider (i.e. the user has never uploaded an avatar).
**Changes**: In Zulip 3.0 (feature level 18), if the client has the **Changes**: In Zulip 3.0 (feature level 18), if the client has the
@ -18653,7 +18653,7 @@ components:
in: query in: query
description: | description: |
Whether to consider only the direct members of user group and not members Whether to consider only the direct members of user group and not members
of its subgroups. Default is `False`. of its subgroups. Default is `false`.
schema: schema:
type: boolean type: boolean
example: false example: false