Should you Combine Swagger with HATEOAS/HAL/JSON-LD?

Question

I am using Swagger for my ASP.NET Core API using Swashbuckle which describes my API in a separate document and provides a nice UI for all of this information.

Are there any advantages of using something like HATEOAS, HAL or JSON-LD which modify the document itself in combination with Swagger?

Here is an example of someone using Swagger with HAL.

Answer 1

There are definite advantages of integrating HATEOAS into your API code in addition to using Swagger.

Swagger adds form to your APIs by making them look good and presentable so that client code can be written easily, at the same time it also makes documentation a much less boring task by integrating it with code. Needless to say, it also saves the extra time it takes to document if done after coding is over. In this sense, it is a bit revolutionary.

HATEOAS on the other hand makes your APIs self discoverable by enabling Level 3 RMM . This makes it easier to navigate through one API to the other. The idea is to have a base URL that a client can use and the rest of the REST APIs are discovered from this base URL.

Now the question is, why have both? Well, it just adds more dimension to your Restful APIs and gives clients more choice for very little coding effort. Who wouldn't want that?