Mostra il valore di esempio XML/JSON nell'interfaccia utente di Swagger utilizzando le annotazioni di swagger

Question

Sto implementando l'API REST basata su Jersey e utilizzando lo swagger per generare la documentazione basata su HTML per lo stesso. Sto usando le annotazioni di swagger per leggere e scansionare le risorse per generare documentazione. Ho specificato di risposta per ogni risorsa utilizzando @ApiResponse annotazione come di seguito:

@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(); 
    } 
} 

Si sta lavorando bene e sta generando la documentazione in base HTML come di seguito:

Come mostra la struttura completa (modello e valore di esempio) della risposta se il codice di risposta è 404. E nel valore di esempio, non mostra i valori, ma mostra solo il tipo per ogni parametro per il modello.

Voglio mostrare lo schema di esempio di esempio per la risposta in modo che il cliente possa capire quale sarebbe la risposta esatta per ogni risposta. Ho cercato su di esso e ho trovato che c'è un attributo:

@ApiResponse (reference = "") - Specifica un riferimento al tipo di risposta. Il riferimento specificato può essere locale o remoto e verrà utilizzato così com'è e sostituirà qualsiasi classe response() specificata.

ho provato e ho dargli un percorso per il mio file sample.json come di seguito:

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

e ho anche cercato di dare un altro percorso che è percorso locale come di seguito:

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

ma quando spavalderia generare documento per esso allora si dà seguito:

Sta visualizzando C: /Desktop/hello.json non è definito!

Ho studiato e provato molte soluzioni ma non sono riuscito a fornire un riferimento adeguato. Ho trovato che questo è un problema di https://github.com/swagger-api/swagger-ui/issues/1700 e https://github.com/swagger-api/swagger-js/issues/606.

Quindi, come posso utilizzare l'attributo di riferimento di @ApiResponse a tale swagger potrebbe mostrare l'interfaccia utente di swagger XML/JSON di esempio. La mia classe del modello è qui sotto:

@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; 
    } 
} 

e voglio mostrare seguente XML di esempio nell'interfaccia utente spavalderia:

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

Answer 1

È necessario annotare la vostra classe del modello (non la risorsa API/metodo!) Con le annotazioni @ApiModel e @ApiModelProperty come described here.

Per quello che si vuole raggiungere, sarebbe probabilmente sufficiente per annotare i membri del modello come segue:

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

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

Se questo non funziona, provare mettendo l'annotazione sui getter (io non sono ho davvero familiarità con il lato XML di questo, l'ho fatto solo per JSON).