The term `parameter` is a better word than `argument` for data passed
to an API endpoint; this is why OpenAPI uses in their terminology.
Replace `argument` with `parameter` in the API docs to improve their
readability.
Fixes#15435.
Currently response return values have to be written twice, once in
the docs and once in zulip.yaml. Create a markdown extension so
that the return values in api docs are rendered using content from
zulip.yaml
Firstly, change endpoint descriptions in zulip.yaml so that they
match their counterpart in the api docs. Then edit the api docs
so that they use api description markdown extension for displaying
endpoint description.
Since the Zulip API runs on both developement and production
servers, it is misleading to mention "dev servers" when discussing
zuliprc files.
Also, note that it is better to manually edit all of our JS
examples than to implement macro-like functionality that we use
for our Python examples. For our current purposes, it would be
too much work to build a full-blown testing framework for our
JS code examples just so that we can fix a minor wording issue.
Fixes#10672.
This commit adds tests for the sample fixture for when a required
request argument is missing. Also, it moves the sample fixture
to common-error-payloads.md, since this is an error payload that
is common to most requests (except the ones that don't take any
arguments).
This commit modifies the Markdown extension in bugdown/api_code_examples.py
to support rendering code examples in multiple languages by specifying
the language like so:
{generate_code_example(python)|doc.md|example}
This makes us one step closer towards adding support for testable
JavaScript code examples.
We now have a separate page for common error payloads, for example,
the payload for when the client's API key is invalid. All error
payloads that are presented on this page will be tested similarly
to our other non-error sample fixtures.
To generate a code exammple,
{generate_code_example|<api_doc_md>|example} sounds better and
more intuitive than,
{generate_code_example|<api_doc_md>|method}
This commit uses the Markdown extension defined in
zerver/lib/bugdown/api_generate_example to generate the example
fixture and code example, so that both are tested in
tools/lib/api_tests.
It makes sense to make our Python and JS API examples more visible
than our curl examples, since Python is what most people will tend
to use.
Also, from a design perspective, an API documentation page that
starts off with a shiny Python example with syntax highlighting
looked much better than having a bland curl example be the first
thing readers see.
Kartik Srivastava
orientor
Vishnu Ks
Eeshan Garg
Yago González