Pokaż przykładową wartość XML/JSON w interfejsie użytkownika Swagger, korzystając z adnotacji typu swagger.

Question

Implementuję interfejs REST API oparty na języku Jersey i używam narzędzia swagger do generowania dokumentacji opartej na języku HTML. Używam adnotacji Swaggera do odczytu i skanowania zasobów w celu wygenerowania dokumentacji. Mam określony odpowiedź dla każdego zasobu używając @ApiResponse adnotacji, jak poniżej:

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

To działa dobrze i jest generowanie dokumentacji w oparciu HTML jak poniżej:

Jak przedstawia kompletną strukturę (model przykładowa) odpowiedzi, jeśli kod odpowiedzi to 404. W przykładowej wartości nie pokazuje wartości, a jedynie pokazuje typ dla każdego parametru dla modelu.

Chcę pokazać przykładowy schemat odpowiedzi, aby klient mógł zrozumieć, jaka jest dokładna odpowiedź dla każdej odpowiedzi. Zbadałem go i odkryłem, że istnieje jeden atrybut:

@ApiResponse (reference = "") - Określa odniesienie do typu odpowiedzi. Podane odwołanie może być lokalne lub zdalne i będzie używane tak, jak jest, i zastąpi każdą określoną klasę response().

Próbowałem go i daję mu drogę do mojego pliku sample.json jak poniżej:

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

i Próbowałem też dać inną ścieżkę, która jest lokalna droga jak poniżej:

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

ale gdy swagger wygenerowania dokumentu za to potem daje następujące:

To pokazuje C: /Desktop/hello.json nie jest zdefiniowany!

Przebadałem i wypróbowałem wiele rozwiązań, ale nie byłem w stanie podać odpowiedniego odniesienia do nich. Zauważyłem, że jest to problem przez https://github.com/swagger-api/swagger-ui/issues/1700 i https://github.com/swagger-api/swagger-js/issues/606.

W jaki sposób mogę użyć referencyjnego atrybutu @ApiResponse do tego przekierowania, może pokazać przykładowy interfejs użytkownika przechwytu XML/JSON. Moja klasa model jest poniżej:

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

i chcę pokazać Poniższy przykładowy kod XML w interfejsie Swagger:

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

Answer 1

trzeba opisywać swoją klasę modelu (nie API zasób/metoda!) Z Adnotacje @ApiModel i @ApiModelProperty jako described here.

Za to, co chcemy osiągnąć, będzie to prawdopodobnie wystarczy do opisywania swoich członków modelu następująco:

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

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

Jeśli to nie zadziała, spróbuj umieścić adnotację na pobierające (nie jestem naprawdę znane z XML strony, zrobiłem to tylko dla JSON).