The javascript tab in .md templates can be
generated along with the line that adds js
example.
Further, as a part of the effort of moving
towards a single template, the markdown extension
for javascrit examples is modified to return empty
string if javascript example doesn't exist for that
endpoint. This would make it possible to cover more
endpoints with a single template.
The js example tabs are now automatically generated
during generation of javascript code, and so need to
be removed. Also, the markdown function to render js
examples can be added in all templates, since it is
parses and returns an empty string if the examples
don't exist, and allows us to move towards a common
template.
The pages have been verified to be correct
by using diff between old and new pages' raw HTML.
The headings for return values were currently hardcoded
in cases where they occur, but they can be rendered directly
in the markdown extension if the return values exist.
Now, the descriptions and all subschemas
are directly returned just by
`generate_code_example`, and so, these individual
subschemas and descriptions can be removed from the
templates.
All API endpoints docs are exactly the same after the
change, except few where missing 400 responses got added
due to the modification
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.
The previous code for the validator test was fairly messy due to
checking for both formats of the openapi url, one with
<variable_name> and the other with {variable_name}. To eliminate
this, we have standardized the format and restricted it to
{variable_name} as per the official format at:
https://swagger.io/docs/specification/describing-parameters.
When passing arguments with the `-d` syntax, which is convenient for
command-line examples, one needs to specify `-X GET` for curl to work
properly.
Fixes#12116
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.
Suyash Vardhan Mathur
Kartik Srivastava
orientor
Vishnu Ks
Hemanth V. Alluri
Eeshan Garg
Sameer Choubey
Yago González