Hateoas: Links entity has wrong structure

[mathias-ewald]

Describe the bug
The _links property of HAL entities are generated as an array of Links. The real structure is an object with the link names as properties.

To Reproduce
Springboot: 2.4.1
Springdoc: 1.5.5

It happens for every entity exposed over Spring Data Rest. An example schema looks like this:

    EntityModelProduct:
      type: object
      properties:
        ...
        _links:
          type: array
          items:
            $ref: '#/components/schemas/Link'

Spring Data Rest does not produce an array:

{
  ...
  "_links" : {
    "self" : {
      "href" : "https://api.edit.local/catalog/products/05c519ab-1735-42c2-9b11-b99926ef9fa1"
    },
    "product" : {
      "href" : "https://api.edit.local/catalog/products/05c519ab-1735-42c2-9b11-b99926ef9fa1{?projection}",
      "templated" : true
    },
    "vendor" : {
      "href" : "https://api.edit.local/catalog/products/05c519ab-1735-42c2-9b11-b99926ef9fa1/vendor"
    }
  }
}

Expected behavior
There should probably be a Links schema for every model. In this case EntityModelProductLinks with self, product and all relations as properties.

[bnasslahsen]

@mathias-ewald,

There are cases where spring-hateoas produces an array of links. This is a working sample.

Please add a complete minimal sample that shows more details about your reported issue.

Here is a sample of the generated structure and there is no array (by default): (some samples are available on the springdoc-data-rest tests)

EntityModelProduct:
  type: object
  properties:
    name:
      type: string
    _links:
      $ref: '#/components/schemas/Links'
    Links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Link'
    Link:
      type: object
      properties:
        href:
          type: string
        hreflang:
          type: string
        title:
          type: string
        type:
          type: string
        deprecation:
          type: string
        profile:
          type: string
        name:
          type: string
        templated:
          type: boolean

This structure is more generic and is also correct.
The additionalProperties can be self, product and all relations as properties.

Having a Links schema for every model is another way of describing the structure, but seems a feature nice to have.

[mathias-ewald]

@bnasslahsen Hmm that's interesting. I noticed that the example you have at http://158.101.164.60:8085/swagger-ui.html is somewhat different to what I see when I use Spring Data Rest. As you said, your _links is an array but also collection elements are in content not _embedded. Where is the code for that?

For a full example to reproduce the behavior I described (_embedded and _links object), please refer to https://github.com/mathias-ewald/springdoc-data-rest-example

Here some code snippets from the repo:

@Entity
@Data
@EqualsAndHashCode(callSuper = false)
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class Pet extends BaseEntity {

	@NotNull
	private String name;
	
	@ManyToOne
	private Owner owner;

}

public interface PetRepo extends JpaRepository<Pet, UUID> {

}

{
  "_embedded" : {
    "pets" : [ {
      "name" : "Charlie",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/pets/ec1ba784-e39e-48cc-979e-7591a6410dc6"
        },
        "pet" : {
          "href" : "http://localhost:8080/pets/ec1ba784-e39e-48cc-979e-7591a6410dc6"
        },
        "owner" : {
          "href" : "http://localhost:8080/pets/ec1ba784-e39e-48cc-979e-7591a6410dc6/owner"
        }
      }
    }, {
      "name" : "Luna",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/pets/fd3f0971-2be5-41bc-a9eb-2734963fb99a"
        },
        "pet" : {
          "href" : "http://localhost:8080/pets/fd3f0971-2be5-41bc-a9eb-2734963fb99a"
        },
        "owner" : {
          "href" : "http://localhost:8080/pets/fd3f0971-2be5-41bc-a9eb-2734963fb99a/owner"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/pets"
    },
    "profile" : {
      "href" : "http://localhost:8080/profile/pets"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 8,
    "totalPages" : 1,
    "number" : 0
  }
}

In the above output, all _link for the entity models and the collection model are objects, not arrays.

[bnasslahsen]

@mathias-ewald,

This is the link of the sample code for hateoas that is deployed as demo:

• https://github.com/springdoc/springdoc-openapi-demos/tree/master/sample-springdoc-openapi-hateoas-service

[mathias-ewald]

@bnasslahsen, you can see in your demo projects, that "manually" using Hateoas (sample-springdoc-openapi-hateoas-service) creates _links as an array but in your spring data rest demo (sample-springdoc-openapi-data-rest), it is generated as an object:

$ curl localhost:8080/customers
{
  "_embedded" : {
    "customers" : [ ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/customers"
    },
    "profile" : {
      "href" : "http://localhost:8080/profile/customers"
    },
    "search" : {
      "href" : "http://localhost:8080/customers/search"
    }
  }
}

I don't know how/why this is happening in the first place, but springdoc should reflect this in the api-doc it generates nonetheless.

[bnasslahsen]

Hi @mathias-ewald,

1. Using Hateoas (sample-springdoc-openapi-hateoas-service) creates _links as an array: The main reason it only uses spring-boot-starter-hateoas, but not spring-data-rest.

2. Using spring data rest demo (sample-springdoc-openapi-data-rest), _links are displayed as an object: The main reason it's based on spring-boot-starter-data-rest.

One of the reasons we have separate springdoc-openapi modules for spring-hateoas and spring-data-rest, is that the dependencies and structure are not really the same.

What is important is that in both cases, the generated api-docs reflects the _links structure, whether it's an array or an object.

I am not seeing any issue in here.

[mathias-ewald]

@bnasslahsen I don't see a problem as long as the api-doc represents what the API actually sends. The reason for my issue is, that spring-data-rest creates an object while the api-doc yaml file describes an array. Therefore, the api-doc does not match the REST API.

[bnasslahsen]

I will close this ticket, as far i think it answers your request.
And it can be reopened, if there are any other updates.

[habibrehmansg]

I am facing this issue where using HAL+JSON with the following dependencies

spring-boot-starter-actuator
spring-boot-starter-data-jpa
spring-boot-starter-hateoas
springdoc-openapi-hateoas

returns _links as Array in api spec whereas the endpoint is returning object only when

show-actuator is set to: true

Is this a bug or expected?