Kann ich reichhaltige, dynamische "Implementierungshinweise" in swagger erstellen?

Question

Ich verwende ApiOperation Anmerkung zur Zeit für meine Web-Services-Methoden in den „Implementierung Anmerkungen“ zu dokumentieren:

@ApiOperation(
    value = "Searches for information", 
    notes = "This service searches for information" 
) 
public Response getInformation(...) 

ich jetzt meine Notizen verbessern möge Eigenschaften Dateien, Informationen aus einer Datenbank zu verwenden, etc. Ich möchte, dass es reich und dynamisch ist. So

, lassen Sie uns sagen, dass ich ein POJO, die Informationen aus der Datenbank enthält:

@Entity 
public class SortColumnField { 
    @Id 
    @Column 
    private String fieldName; 
    @Column 
    private String fieldDescription; 
} 

Gibt es etwas, das mir erlauben würde, Prahlerei Dokumentation von Objekten wie diese zu erzeugen?

Answer 1

Sie haben zwei Möglichkeiten, dies zu tun.

Erstens unterstützt die Notizen Abschnitt Abschrift, speziell Github-aromatisiert. Sie können ziemlich reichhaltige Informationen in diesem Abschnitt haben und die meisten Tools werden es richtig rendern.

Als nächstes unterstützt die Operation Object ein Feld namens externalDocs. Wenn Sie nicht in Swagger-UI gerendert werden, können Sie die Benutzeroberfläche leicht aufteilen, um auf Ihre komplexen Dokumente zu verweisen, die möglicherweise nicht in die Struktur passen, die in den Standardwerkzeugen gerendert wird.