Zeigen Sie XML/JSON-Beispielwert in Swagger UI mit Protokollen von Swagger

Question

Ich bin auf Jersey-basierte REST-API implementieren und verwenden Swagger, um HTML-basierte Dokumentation für die gleichen zu generieren. Ich verwende Swagger-Annotationen, um die Ressourcen zu lesen und zu scannen, um Dokumentation zu generieren. Ich habe für jede Ressource angegeben Antwort @ApiResponse Anmerkung wie unten:

@Path("/hello") 
@Api(value = "Hello World") 
public class HelloRest 
{ 
    @GET 
    @ApiOperation(value="Hello world", httpMethod="GET") 
    @ApiResponses(value={ @ApiResponse(code = 200, message = "Success", response = WebservicesErrorResponse.class, reference = "C:/Desktop/hello.json") 
          @ApiResponse(code = 404, message = "Not found", response = WebservicesErrorResponse.class)}) 
    @Produces({"application/json", "application/xml"}) 
    public Response helloWorld() 
    { 
     return Response.status(WebservicesCommonTypes.SUCCESS).entity("Hello rest API").build(); 
    } 
} 

Es funktioniert gut und es erzeugt HTML-basierte Dokumentation wie folgt:

Da es die komplette Struktur (Modell zeigt und Beispielwert) der Antwort, wenn der Antwortcode 404 ist. Und im Beispielwert werden nicht die Werte angezeigt, sondern nur der Typ für jeden Parameter für das Modell.

Ich möchte das Beispielschema für die Antwort zeigen, so dass der Client verstehen kann, was genau die Antwort für jede Antwort wäre. Ich erforschte es und ich fand, dass es ein Attribut gibt:

@ApiResponse (reference = "") - Gibt einen Verweis auf den Antworttyp an. Die angegebene Referenz kann entweder lokal oder remote sein und wird wie sie ist verwendet. Sie überschreibt alle angegebenen response() -Klassen.

Ich versuchte es und ich gebe es einen Weg für meine sample.json Datei wie folgt:

@ApiResponse(code = 200, message = "Success", response = WebServicesErrorResponse, reference = "http://localhost:9001/myinstanceofapplication/html/api-doc/hello.json") 

und ich habe auch versucht, einen anderen Weg zu geben, wie lokale Pfad unten:

@ApiResponse(code = 200, message = "Success", response = WebservicesErrorResponse.class, reference = "C:/Desktop/hello.json") 

aber als Prahlerei Dokument für sie erzeugen dann ergibt es folgende:

Es zeigt C: /Desktop/hello.json ist nicht definiert!

Ich habe viele Lösungen recherchiert und ausprobiert, konnte aber nicht richtig darauf verweisen. Ich habe festgestellt, dass dies ein Problem von https://github.com/swagger-api/swagger-ui/issues/1700 und https://github.com/swagger-api/swagger-js/issues/606 ist.

Also wie kann ich Referenzattribut von @ApiResponse zu diesem Swagger verwenden könnte die Beispiel XML/JSON Swagger UI anzeigen. Meine Modellklasse ist unter:

@XmlRootElement(name="response") 
@XmlAccessorType(XmlAccessType.FIELD) 
public class WebservicesErrorResponse 
{ 
    @XmlElement 
    private int code; 

    @XmlElement 
    private String message; 

    public WebservicesErrorResponse(){ } 


    public WebservicesErrorResponse(int code, String message) 
    { 
     this.code = code; 
     this.message = message; 
    } 

    public int getCode() 
    { 
     return code; 
    } 
    public void setCode(int code) 
    { 
     this.code = code; 
    } 

    public String getMessage() 
    { 
     return message; 
    } 
    public void setMessage(String message) 
    { 
     this.message = message; 
    } 
} 

und ich möchte in den Prahlerei UI folgenden XML-Beispiel zeigen:

<?xml version="1.0"?> 
<response> 
    <code>200</code> 
    <message>success</message> 
</response> 

Answer 1

Sie benötigen eine Modellklasse mit Anmerkungen versehen (nicht die API-Ressource/Methode!) Mit die @ApiModel und @ApiModelProperty Anmerkungen wie described here.

Für das, was Sie erreichen wollen, ist es wahrscheinlich ausreichen würde Ihr Modell Mitglieder mit Anmerkungen zu versehen, wie folgt:

@ApiModelProperty(example = "200") 
@XmlElement 
private int code; 

@ApiModelProperty(example = "success") 
@XmlElement 
private String message; 

das nicht funktioniert, wenn, versuchen Sie auf den Getter die Anmerkung setzen (ich bin nicht wirklich vertraut mit der XML-Seite von diesem, habe es nur für JSON getan).