search

influxdata / openapi

An OpenAPI specification for influx (cloud/oss) apis.
MIT License
17 stars 10 forks source link

Move code, response, request samples to `examples` and `x-codeSample` elements #543

Open jstirnaman opened 1 year ago

jstirnaman commented 1 year ago

@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.

Originally posted by @jstirnaman in https://github.com/influxdata/openapi/issues/541#issuecomment-1252922994