Spring Data REST Excerpt projections are missing from spec

[janjouketjalsma]

Describe the bug
Spring Data REST allows you to define an excerpt projection for an entity. Adding this will automatically embed this projection whenever the entity is shown as part of a parent collection.

From the docs:

(...) The preceding example directs Spring Data REST to use the NoAddresses projection when embedding Person resources into collections or related resources.

It looks like this excerpt projection functionality is not (correctly) covered by Spring Doc because the embed is not showing up in the generated OpenAPI spec.

To Reproduce
Steps to reproduce the behavior:

• Spring Boot: 3.2.5
• Packages:
  • org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0
  • org.springdoc:springdoc-openapi-starter-webmvc-api:2.5.0
  • org.springdoc:springdoc-openapi-starter-common:2.5.0
• Steps
  • Create an entity with a relationship to another entity
  • Create an excerpt projection for the second entity
  • Check the OpenAPI spec for the first entity and verify if the excerpt projection is part of it

Reproducer project: https://github.com/janjouketjalsma/spring-doc-excerpt-projection-issue-reproducer

Current behaviour
Only the direct properties of the main entity end up in the spec.

      "EntityModelBookStoreEntity": {
        "required": [
          "books",
          "name"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "_links": {
            "$ref": "#/components/schemas/Links"
          }
        }
      },

Expected behavior
I expect the excerpt projection to be part of the spec for the main entity.

Example: (Bookstore is the main entity, Book is the one with the excerpt projection)

      "EntityModelBookStoreEntity": {
        "required": [
          "books",
          "name"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "_embedded" : {
            "type": "object",
            "properties": {
              "books": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "_links": {
                      "$ref": "#/components/schemas/Links"
                    }
                  }
                }
              }
            }
          }
          "_links": {
            "$ref": "#/components/schemas/Links"
          }
        }
      },

(or maybe with a $ref, not sure what would be the implementation)

[quocanha]

I'm having a similar use-case where I want to use Spring Data Rest to provide the standard CRUD endpoints. I do not have the answer to OP, but want to voice my journey so far since it is the same use-case.

Additional to the standard out-of-the-box configuration of SDR, in order to minimize http calls, I want to use Excerpts and Projections, as mentioned in OP, to return more data than is strictly REST in these endpoints. Unfortunately I encountered the same problem that these Projections are not represented in the resulting OpenAPI spec.

I have found https://dzone.com/articles/extending-swagger-and-spring-doc-open-api (from https://springdoc.org/#other-resources), which looks very promising in terms of adding properties. The crux of the article is to extend the ModelResolver class that is used by Swagger and override the methods that it uses.

Unfortunately, my mind slowly implodes with my attempts to make sense of its main resolve function comprising of 800 lines.

My current understanding is that this is a recursive function that is called for each property of an object, which is a yet rather superficial description of what it does. My attempts at overriding the methods all failed due to me not properly understanding how to add properties to the current Schema object.

Although unconfirmed, I suspect to have found the required pieces once I know how to add properties to the schema, which entails retrieving all projections (using the EntityManager and then ProjectionDefinitionConfiguration::getProjectionsFor).

[bnasslahsen]

@janjouketjalsma and @quocanha,

This is an enhancement request.
If you have identified, how to add the additional attributes feel to propose a PR.

[ashish3805]

+1 I am facing this issue as well