influxdata / influxdata/openapi
Move code, response, request samples to `examples` and `x-codeSample` elements
@sunbryely-influxdata is already working on this.
Since Sep 20, 2022.
- Dominant language
- Shell
- Stars
- 18
- Forks
- 9
- PR merge metrics
- No merged PRs in 30d
Description
> > @sranka Can you elaborate on this: is it causing a problem or not rendered or...?
>
> Even though swagger/openapi allows to use Markdown in descriptions, the existing code generators (from swagger to a specific programming language) do not implement any translation logic to convert markdown text to what is expected in a given language. The tripple-backtick code markdown block that was used herein as an example
>
> * is understood by python `pdoc3` API documentation generator (was wrong, repaired in this PR)
> * requires extra pre-processing in javascript client, because the javascript build tools wrongly indent the code blocks that are then not recognized by typescript api-documenter
> * is not understood in java (`
{@code ...}` is used)
> * is not understood in c# (`
` is used)
> * is not understood in ruby (`=begin =end` is used)
> * ... other apidoc generators might not render description elements at all
>
> The tripple backticks probably have no meaning when they are not understood ... they appear in the generated code, but the code block can lose indentantion and it could be merged to appear as a continuous text in a paragraph.
Thanks for the detailed explanation. @sunbryely-influxdata and I will move code samples from `description` elements to elements defined for examples (`example`, `examples`, and `x-codeSample`) and reserve future samples to those elements.
_Originally posted by @jstirnaman in https://github.com/influxdata/openapi/issues/541#issuecomment-1252922994_
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.