Spring HATEOAS support

[valentinabojan]

Hi!

I'm trying to setup springdoc-openapi in my project and I'm facing an issue regarding the docs generated for HAL objects.
Used dependencies:

• springdoc-openapi-ui - 1.3.1
• springdoc-openapi-data-rest - 1.3.1
• spring boot - 2.2.5.RELEASE

I have defined a REST endpoint that will respond with the following data example:

{
  "_embedded": {
    "albums": [
      {
        "title": "album-title-1",
        "description": "album-description-1",
        "releaseDate": "album-release-date-1"
      },
      {
        "title": "album-title-2",
        "description": "album-description-2",
        "releaseDate": "album-release-date-2"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "http://localhost:8080/api/albums"
    }
  },
  "page": {
    "size": 2,
    "totalElements": 2,
    "totalPages": 1,
    "number": 0
  }
}

However, the schema for the response looks differently:

{
  "links": [
    {
      "rel": "string",
      "href": "string",
      "hreflang": "string",
      "media": "string",
      "title": "string",
      "type": "string",
      "deprecation": "string",
      "profile": "string",
      "name": "string"
    }
  ],
  "content": [
    {
      "title": "string",
      "description": "string",
      "releaseDate": "string",
      "links": [
        {
          "rel": "string",
          "href": "string",
          "hreflang": "string",
          "media": "string",
          "title": "string",
          "type": "string",
          "deprecation": "string",
          "profile": "string",
          "name": "string"
        }
      ]
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  }
}

This is how I implemented the endpoint:

@RestController
public class WebController {

    @Autowired
    private AlbumModelAssembler albumModelAssembler;
    @Autowired
    private PagedResourcesAssembler pagedResourcesAssembler;

    @GetMapping("/api/albums")
    public PagedModel<Album> getAllAlbums() {
        Album album1 = new Album("album-title-1", "album-description-1", "album-release-date-1");
        Album album2 = new Album("album-title-2", "album-description-2", "album-release-date-2");
        Page<Album> albumPage = new PageImpl<>(Arrays.asList(album1, album2));

        return pagedResourcesAssembler.toModel(albumPage, albumModelAssembler);
    }

}

You can also find the full example here.

Has springdocs-openapi support for HAL objects? Is there any configuration that I'm missing? Thank you!

[valentinabojan]

When adding the org.springframework.data:spring-data-rest-webmvc dependency, we got the following results:

In apidocs.json:

// 20200410123844
// http://localhost:8080/v3/api-docs

{
  "openapi": "3.0.1",
  "info": {
    "title": "Albums API",
    "termsOfService": "No Terms of service URL specified",
    "license": {
      "name": "No License specified"
    }
  },
  "servers": [
    {
      "url": "http://localhost:8080",
      "description": "Generated server url"
    }
  ],
  "paths": {
    "/api/albums": {
      "get": {
        "tags": [
          "web-controller"
        ],
        "operationId": "getAllAlbums",
        "responses": {
          "200": {
            "description": "default response",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/PagedModelAlbum"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Album": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "releaseDate": {
            "type": "string"
          }
        }
      },
      "Links": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/Link"
        }
      },
      "PageMetadata": {
        "type": "object",
        "properties": {
          "size": {
            "type": "integer",
            "format": "int64"
          },
          "totalElements": {
            "type": "integer",
            "format": "int64"
          },
          "totalPages": {
            "type": "integer",
            "format": "int64"
          },
          "number": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "PagedModelAlbum": {
        "type": "object",
        "properties": {
          "_embedded": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Album"
              }
            }
          },
          "_links": {
            "$ref": "#/components/schemas/Links"
          },
          "page": {
            "$ref": "#/components/schemas/PageMetadata"
          }
        }
      },
      "Link": {
        "$ref": "#/components/schemas/Link"
      }
    }
  }
}

This looks closer to what we expect (ie. "_embedded" instead of "content"), but there is still a problem. The spring resource is outputting "albums", but the documentation is generating "additionalProperties" instead.
This makes it impossible to make a client from the generated documentation.

[bnasslahsen]

@valentinabojan,

The support of _embedded instead of content, depends on the existance of RepositoryRestConfiguration and the setting useHalAsDefaultJsonMediaType.
The springdoc-openapi-data-rest is tested against spring-boot-starter-data-rest which ships this class.

For the usage with spring-boot-starter-hateoas, it's not yet validated. If you are expecting the same behaviour as with spring-boot-starter-data-rest, we look for the setting in spring-boot-starter-hateoas that declares the HAL is used as default json media type.

[valentinabojan]

Hi, there is still the issue we mentioned above, about the "additionalProperties" field name enclosed in "_embedded". This should have the name of the class, such as "albums".

We are working on a fix for this.