Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/api_docs/api-doc-template.md

32 lines
609 B
Markdown
Raw Permalink Normal View History

openapi: Fuse generate_api_title with generate_api_description. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-07-21 00:01:06 +02:00
{generate_api_header(API_ENDPOINT_NAME)}
api docs: Replace most markdown files with a common template. This PR adds a basic .md template that is followed by lot of /api pages. Since we have recently done the migration work to ensure that our REST API documentation pages for individual endpoints are almost all identical files following a common pattern, we can now get the payoff of deleting them all in favor of a shared template. This removes 2000 lines of somewhat finicky configuration from the codebase, and thus should save significant effort when documenting new API endpoints in the future. The markdown files for endpoints or other pages which deviate from the standard template remain, and the docs are instead generated from those files using the existing system.
2021-05-23 13:27:41 +02:00
## Usage examples
{start_tabs}
{generate_code_example(python)|API_ENDPOINT_NAME|example}
{generate_code_example(javascript)|API_ENDPOINT_NAME|example}
{tab|curl}
{generate_code_example(curl)|API_ENDPOINT_NAME|example}
{end_tabs}
## Parameters
{generate_api_arguments_table|zulip.yaml|API_ENDPOINT_NAME}
{generate_parameter_description(API_ENDPOINT_NAME)}
## Response
{generate_return_values_table|zulip.yaml|API_ENDPOINT_NAME}
{generate_response_description(API_ENDPOINT_NAME)}
api-docs: Update example response header for potential plural. The documentation for various API endpoints gives multiple response examples. Update the headers to reflect this fact.
2022-11-07 20:35:08 +01:00
#### Example response(s)
api docs: Replace most markdown files with a common template. This PR adds a basic .md template that is followed by lot of /api pages. Since we have recently done the migration work to ensure that our REST API documentation pages for individual endpoints are almost all identical files following a common pattern, we can now get the payoff of deleting them all in favor of a shared template. This removes 2000 lines of somewhat finicky configuration from the codebase, and thus should save significant effort when documenting new API endpoints in the future. The markdown files for endpoints or other pages which deviate from the standard template remain, and the docs are instead generated from those files using the existing system.
2021-05-23 13:27:41 +02:00
openapi: Render all responses of an operation. Previously, one needed to specifying all the HTTP status codes that we want to render along with the operation, but the primary use case just needs the responses of all the status codes, and not just one. This commit modifies the Markdown extension to render all the responses of all status codes of a specified operation in a loop.
2021-07-13 17:33:43 +02:00
{generate_code_example|API_ENDPOINT_NAME|fixture}