Generating Wrapped API Documentation for Models with Restlet Swagger 2 and XStream

[kerbymart]

Issue Description:

In the context of using the Restlet Framework with Swagger 2 and XStream extensions, there is a challenge in accurately representing the wrapped model structure in the Swagger API documentation. The discrepancy arises due to the XStream serialization wrapping the model class, which Swagger 2 cannot directly document.

Model Class

The User model is defined with Swagger and XStream annotations:

@ApiModel
@XStreamAlias("user")
@Entity
@Table(name = "user")
public class User {}

Endpoint Resource

The endpoint for creating a new user uses the following method signature:

@ApiOperation(value = "Create a new user", response = UserResponse.class)
@Post
User createUser(User user);

Response Wrapper Class

To address the serialization wrapping, a placeholder class, UserResponse, is introduced for Swagger documentation:

/**
 * Placeholder class for API documentation.
 * 
 * This class is specifically for Swagger annotations to provide API documentation. 
 * It's necessary because the actual models are wrapped due to the usage of XStream converters, 
 * and Swagger 2 cannot directly document wrapped models.
 */
@ApiModel(value = "UserResponse", description = "Response format for User")
public class UserResponse {
    @ApiModelProperty(required = true, value = "User details")
    private User user;
}

Discrepancy in JSON Output

The challenge is that XStream expects the JSON payload to include a wrapper, like this:

Expected JSON format for XStream:

{
  "user": {
    "username": "testuser",
    "passwordHash": "testpass",
    "email": "[email protected]"
  }
}

However, Swagger generates documentation based on the UserResponse class, which may not explicitly convey this wrapping:

Swagger-documented JSON format:

{
    "username": "testuser",
    "passwordHash": "testpass",
    "email": "[email protected]"
}

Problem Statement

The core issue is that Swagger 2, as used with Restlet Framework, does not natively support documenting models that are wrapped by XStream. The UserResponse class is used as a workaround to provide API documentation, but also does not work as intended.

[jlouvel]

Hi @kerbymart Thanks for submitting this issue. We have deprecated support for XStream in version 2,3 and removed it in 2.4 due to the perceived lack of usage and Restlet level, plus the lack of activity on XStream itself (last maintenance version was in Dec. 2022).

Have you considered moving to Jackson or GSON extensions instead, if not what is preventing you from doing that? JAXB could be another alternative.