Move code, response, request samples to `examples` and `x-codeSample` elements
@sunbryely-influxdata ci sta già lavorando.
Dal 20/9/2022.
Valutazione
Questa issue non è ancora stata valutata.
Descrizione
@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
pdoc3API 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 =endis 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
- Lingua principale
- Shell
- Stelle
- 18
- Fork
- 9
- Merge medio
- 2g 18h
- PR unite (30g)
- 1
Preparare l'ambiente
Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di influxdata/openapi
-
Add missing Cloud Routes keysForse già presa @jstirnaman l’ha presa 2 giorni fa. Aperta
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 85/100
influxdata/openapi#660 ·
-
documentation
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
influxdata/openapi#657 ·
-
Difficoltà 1/5 1-3 ore Idoneità per principianti 85/100
influxdata/openapi#653 ·
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 65/100
influxdata/openapi#240 ·
-
Update /ready and /health schemas for v2.10Forse già presa @devanbenz l’ha presa 2 giorni fa. Aperta
influxdata/openapi#659 · 1 commento · 2 assegnatari ·
Tutte le issue di influxdata/openapi
Issue simili
-
Set wallpaperApertanew-addition
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 60/100
-
needs-triage Platform(Default)
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
I maintainer di solito rispondono entro 1 giorno
-
triage
Difficoltà 2/5 1-3 ore Idoneità per principianti 70/100
winapps-org/winapps#984 ·
-
Bluetooth can't be turned back on from the bar on ThinkPads: rfkill block removes the adapterAperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 74/100
I maintainer di solito rispondono entro 1 giorno
-
[Linux] --calibrate combined with --model silently falls through to plain re-setup (setup.py:4958)Forse già presa Una pull request collegata a questa issue è aperta o già unita. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 75/100
I maintainer di solito rispondono entro 1 giorno