Swagger and RESTful spring hateoas resources

Question

In my RESTful API, all resources are extending the Spring's ResourceSupport base, in order to ensure hateoas principals by design. For example:

public class PoolResource extends ResourceSupport {
    private String name;
    ...
}

I'm also using Swagger, and i was wondering: is it possible to configure the swagger-ui somehow, to ignore the properties coming from ResourceSupport?

(Swagger-ui provides a nice and easy frontend of the API. As one of the major benefits of using Swagger, the API is easy to understand and play around with the API for those, who are not even familiar with the REST API... as long as the "links" and "rels" come into the picture.)

Answer 1

I would suggest to throw away swagger and use a restclient like Postman . Postman makes the links provided by spring-hateoas clickable, so you can navigate through the API pretty quickly. If you want to provide some additional information/documentation, you can save those requests into a request collection in Postman and export it for distribution. After I have tried several documentation tools for rest apis, including raml, swagger, apiary and finally Postman-collections in combination with hateaos, I have found the latter to be the one I am most satisfied with.

Answer 2

With Spring Data REST 2.4.0.RELEASE, you now have multiple forms of metadata:

• ALPS
• JSON Schema
• Install the HAL Browser via spring-data-rest-hal-browser module and surf via the hypermedia

Answer 3

The only reasonable way of hiding it would be to hide it from the model itself (there are several ways of doing that, though if you use Spring MVC, I'm not sure what swagger-springmvc supports).

You could theoretically hack swagger.js to hide it, but that's a whole adventure.

Answer 4

Spring RestDocs was built with hyermedia in mind. It works to provide the same benefit as swagger in the "generated docs" realm but isn't so URL based.

http://docs.spring.io/spring-restdocs/docs/current/reference/html5/#getting-started-build-configuration

Strives to output something more align with githubs docs (Hyermedia'd).

https://developer.github.com/v3/#current-version

Answer 5

Any one looked HAL Browser

http://api.opensupporter.org/hb2/browser.html#/api/v1

It helps visualise the web of relationships between resources, so doesnt necessarily show request examples for a resource, but does have areas to display documentation.

My thoughts are it would be an easier way to get a Hateos implementation self documented, to an extent. And perhaps one of those hypermedia links could be a swagger website or Acceptable values could be in the docs I mentioned above.

Answer 6

Don't extend ResourceSupport . Instead, for input model use POJO Pool , and for response use org.springframework.hateoas.Resource(s)<Pool> which wraps your POJO and allows to define links.