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

api-docs: Remove include links in endpoint descriptions. 

Two endpoints had linked markdown files that were used in
their general descriptions to add warning notes with important
information (`/create-user` and `/get-user-groups`).

This moves the warning content to be inline in the endpoint
descriptions so that the important content is in the OpenAPI
documentation and is still formatted to be rendered in a warning
block.

Deletes `can-create-users-only.md` and `api-members-only.md`
since they were only used for these two endpoint descriptions.

Also, cleans up the other instance of a inline warning block in
an endpoint description (`/fetch-api-key`).
This commit is contained in:
Lauryn Menard 2022-06-21 17:46:31 +02:00 committed by Tim Abbott
parent 8a0070ace7
commit 6e924125ad
3 changed files with 23 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
templates/zerver/help/include/api-members-only.md
View File

@ -1,4 +0,0 @@
!!! warn ""
This endpoint is only available to Members and Administrators;
bots and guests cannot use this endpoint.

13
templates/zerver/help/include/can-create-users-only.md
View File

@ -1,13 +0,0 @@
!!! warn ""
This endpoint is limited to organizations administrators who
additionally have the `can_create_users` permission for the Zulip organization.
Zulip Cloud users can request the `can_create_users` permission for a bot by contacting
[Zulip Cloud support](/help/contact-support) with an explanation for why it is needed.
Self-hosted installations can toggle `can_create_users` on an account using
the `manage.py change_user_role` command.
**Changes**: Before Zulip 4.0 (feature level 36), this endpoint was
available to all organization administrators.

29
zerver/openapi/zulip.yaml
View File

@ -64,8 +64,8 @@ paths:
**Note:** If you signed up using passwordless authentication and
never had a password, you can [reset your password](/help/change-your-password).
See the [API keys](/api/api-keys) documentation for
more details on how to download API key manually.
See the [API keys](/api/api-keys) documentation for more details
on how to download an API key manually.
In a [Zulip development environment](https://zulip.readthedocs.io/en/latest/development/overview.html),
see also [the unauthenticated variant](/api/dev-fetch-api-key).
@ -6319,11 +6319,24 @@ paths:
summary: Create a user
tags: ["users"]
description: |
{!can-create-users-only.md!}
Create a new user account via the API.
`POST {{ api_url }}/v1/users`
!!! warn ""
**Note**: This endpoint is limited to organization administrators
who additionally have the `can_create_users` permission for the Zulip
organization. Zulip Cloud users can request the `can_create_users`
permission for a bot by contacting [Zulip Cloud support][support]
with an explanation for why it is needed. Self-hosted installations
can toggle `can_create_users` on an account using the `manage.py
change_user_role` command.
**Changes**: Before Zulip 4.0 (feature level 36), this endpoint was
available to all organization administrators.
[support]: /help/contact-support
x-requires-administrator: true
parameters:
- name: email
@ -13962,11 +13975,15 @@ paths:
summary: Get user groups
tags: ["users"]
description: |
{!api-members-only.md!}
Fetches all of the user groups in the organization.
`GET {{ api_url }}/v1/user_groups`
!!! warn ""
**Note**: This endpoint is only available to [members and
administrators](/help/roles-and-permissions); bots and guests
cannot use this endpoint.
responses:
"200":
description: Success.