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.)

Downcast

If you don't want hypermedia, why are you using Spring HATEOAS in the first place? If you want hypermedia, why are you using Swagger (which actively subverts hypermedia)? – Estelleesten

I want hypermedia. After researching RESTful principals, I understood the benefits of having hypermedia, so I really wanted to design a level 3 API. That's the reason why using Spring HATEOAS. But most users of the API are still not aware of hypermedia, and do not understand why is it good at all. For them, swagger provides a very cool view of the full API. It very good to present it to anybody, and easy to understand even from my grandma to a senior developer. What do you mean Swagger "subverts hypermedia"? – Lymphatic

Most answers suggest me not to use swagger, glory of REST will solve most of my questions. Okay, so lets imagine, I throw away swagger. This leads me to questions like this than: - I have resource Pool. What if I have a newly installed system, without any existing pool instance, so I cannot GET a pool. How to create (POST) a pool than? How does the pool look like? - What about optional fields? Validations? Required... etc? - What about "offline" documentation? – Lymphatic

It was mentioned in this blog post blog.zenika.com/2013/07/11/… that swagger and hateoas are complementary. Swagger helps us to document our APIs but the resource should still expose links to navigate across each other. – Rhetor

Any light on this? I'm facing a similar problem here #38695234 – Cap

And so, what is the question here ? – Motta

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.

Rockel

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

Plating

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.

Casework

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

Haygood

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.

Pedanticism

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.

Eichler