Spring-restdocs: wie man Parameter, Pfade und Antwortfelder Code Blöcke

Question

Ich benutze Spring-Restdocs, um API-Dokumente zu generieren, und ich möchte alle Parameter, Pfade und Antwortfeld JSON-Pfade als Codeabschnitte gedruckt werden (Backticks in Asciidoc) in den Tischen.

Zum Beispiel, die JSON-Pfad-Ketten. []. Widgets. []. ContentType ist schwerer zu lesen in einer Schriftart mit variabler Breite als sprockets.[].widgets.[].contentType, gedruckt in Monospace.

Das Gleiche gilt für Anfrageparameter und Pfadparameter - das sind Token, die in Monospace gedruckt werden sollen.

Was ist der einfachste Weg dies mit Spring-Restdocs zu erreichen?

Vielen Dank im Voraus für jede Hilfe.

G

Answer 1

Ich denke, dass REST Docs dies standardmäßig tun sollten. Ich habe ein Problem behoben, das in 1.1 behoben wird: https://github.com/spring-projects/spring-restdocs/issues/230. Danke für den Vorschlag.

In der Zwischenzeit können Sie tun, was Sie wollen, indem Sie custom snippet templates verwenden. Zum Beispiel die Formatierung der Pfade der Anforderungsfelder anzupassen, benötigen Sie eine request-fields.snippet Datei in src/test/resources/org/springframework/restdocs/templates zu schaffen, der wie folgt aussieht:

|=== 
|Path|Type|Description 

{{#fields}} 
|`{{path}}` 
|{{type}} 
|{{description}} 

{{/fields}} 
|=== 

Beachten Sie die Backticks um {{path}}.

Answer 2

Sie können auch die asciidoctor Formatierungscodes wie ‚m‘ für Monospace verwenden:

m|{{path}} 

Sie auch Spaltenbreiten und die Ausrichtung, beispielsweise drei Spalten mit relativen Breiten 4-4-2 und dritten ändern Säulenmitte ausgerichtet:

[cols="2*4,^2"] 
|=== 
|Parameter|Description|Optional 

(ich weiß, das ist nicht das, was Sie gefragt, aber für Anyo feder restdocs Benutzer neu zu asciidoc vielleicht hilft es zu wissen, dass es viele einfache Möglichkeiten zur Individualisierung)

Siehe http://asciidoctor.org/docs/user-manual/#cols-format