fix: repair code fence backticks in descriptions

[sranka]

Fixes #540

It repairs 2 src/common/schemas type descriptions to have code fence backticks at the start of the line and regenerates the rest. There are then no warnings when running oats typescript code generator on the modified oss.yml.

Note also that the code generated in InfluxDB clients (from swagger) will not understand the intention of backtick Markdown code blocks. Anyway, I also had to repair these backticks in an extra post-processing step in influxdb-client-js using a custom node script.

[sranka]

@jstirnaman please take a look, I repaired the parts that you created/changed.

[sranka]

FYI: the code generated in InfluxDB clients will not understand the intention of backtick Markdown code blocks.

[jstirnaman]

FYI: the code generated in InfluxDB clients will not understand the intention of backtick Markdown code blocks.

@sranka Can you elaborate on this: is it causing a problem or not rendered or...?

[sranka]

@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 (<pre>{@code ...}</pre> is used)
• is not understood in c# (<code></code> 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.

[jstirnaman]

@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 (<pre>{@code ...}</pre> is used)
• is not understood in c# (<code></code> 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.