Hateoas fields names mismatch

[jlefebvre-vsct]

The naming of the fields does not match the HAL specification draft (link) : the generated documentation (based on EntityModel) and the actual JSON representations are different, e.g. "links" instead of "_links" and using default name "content" instead of the specified one by using @org.springframework.hateoas.server.core.Relation(collectionRelation = "components") on the object class.

I am using Spring-boot 2.2.x and Springdoc-openapi 1.2.30.

The expected behavior is that the generated OpenAPI3 contract matches the effective produced data structure (the purpose of generating from sources 😄).

[bnasslahsen]

@jlefebvre-vsct,
As you seem to know well the specification, can you provide a PR about it?

[jlefebvre-vsct]

Hi @bnasslahsen sorry, I don't know the spec well but the generated openapi doesn't match what is actually produced and I don't manage to get them match (any workaround ?).

I have prepared the following demo to illustrate and facilitate further investigation :

• https://github.com/jlefebvre-vsct/springdoc-issue401

Useful demo endpoints :

• http://localhost:8080/swagger-ui.html
• GET http://localhost:8080/components/1 (one result)
• GET http://localhost:8080/components (page of results)

Notable differences :

• "links" instead of "_links"
• "links" structure is wrong (should be a map of links by their name instead of an array)
• "content" should be wrapped inside an "_embedded"
• "content" should be named "components" (in this example)
• "content" structure is wrong (links instead of payload type)

[jlefebvre-vsct]

I don't know springdoc nor swagger at all but I looked at them to figure out how to fix these problems.
I noted the following start points but I didn't manage to fix the schema even a quite dirty way :

• injecting a bean "List" should allow us to customize the properties :
  Schema customize(Schema property, AnnotatedType type);
• SpringDocAnnotationsUtils#extractSchema
• use customizers to change the schema after it has been generated (depends on how swagger-core stores the models)

[jlefebvre-vsct]

"content" of PagedModel was wrong because I was using ResponseEntity<PagedModel<RepresentationModel<EntityModel>> instead of ResponseEntity<PagedModel<EntityModel>

[jlefebvre-vsct]

everything matches when NOT using HAL format 👍

@Configuration
public class SpringRestConfiguration implements RepositoryRestConfigurer {
	@Override
	public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config) {
		config.setDefaultMediaType(MediaType.APPLICATION_JSON);
		config.useHalAsDefaultJsonMediaType(false);
	}
}

and

spring.hateoas.use-hal-as-default-json-media-type: false

[bnasslahsen]

Hi @jlefebvre-vsct,

Thank you for providing all this relevant information.
With v1.2.31, a better support for HAL fields naming (_links, _embedded, ...) will be added.

BTW, for your sample you just need to declare springdoc-openapi-ui and springdoc-openapi-data-rest:

• springdoc-openapi-webmvc-core is by transitivity included in springdoc-openapi-ui.
• The same applies for classgraph.

[ch4mpy]

@bnasslahsen Is there any doc about "better support for HAL fields naming" ?
I'm trying with 1.3.4 but have no idea how to generate the schemas for an HATEOAS app configured with @EnableHypermediaSupport(type = HypermediaType.HAL)

[bnasslahsen]

Hi @ch4mpy,

By default, you just need to add springdoc-openapi-data-rest:

• https://springdoc.org/

You can have a look at some code examples in the tests:

• https://github.com/springdoc/springdoc-openapi/tree/master/springdoc-openapi-data-rest/src/test/java/test/org/springdoc/api/app4
• https://github.com/springdoc/springdoc-openapi/tree/master/springdoc-openapi-data-rest/src/test/java/test/org/springdoc/api/app6
• https://github.com/springdoc/springdoc-openapi/tree/master/springdoc-openapi-data-rest/src/test/java/test/org/springdoc/api/app8

[ch4mpy]

@bnasslahsen thank you for your answer. I had missed the parapgraph about Pageable support (I don't know how as I applied the security one...)

The json schema now seems ok. Unfortunately, openapitools (4.3.0) then fails to process it:

[main] INFO  o.o.c.l.TypeScriptAngularClientCodegen - generating code for Angular 9.0.0 ...
[main] INFO  o.o.c.l.TypeScriptAngularClientCodegen -   (you can select the angular version by setting the additionalProperty ngVersion)
Exception in thread "main" java.lang.StackOverflowError
        at java.base/java.lang.String.startsWith(String.java:1470)
        at org.openapitools.codegen.utils.ModelUtils.getSimpleRef(ModelUtils.java:342)
        at org.openapitools.codegen.utils.ModelUtils.unaliasSchema(ModelUtils.java:1025)
        at org.openapitools.codegen.utils.ModelUtils.unaliasSchema(ModelUtils.java:1066)

but I couldn't yet figure out if it's related to a bad schema or bogous tool...

[ch4mpy]

@bnasslahsen I think the issue in in springdoc: Link schema definition is a reference to itself (missing definition and parsing results in an infinite loop).

I opened an issue for that: #609