search

springdoc / springdoc-openapi

Library for OpenAPI 3 with spring-boot
https://springdoc.org
Apache License 2.0
3.25k stars 489 forks source link

Spring Data REST Excerpt projections are missing from spec #2581

Open janjouketjalsma opened 4 months ago

janjouketjalsma commented 4 months ago

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:

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 commented 3 months ago

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 commented 2 months ago

@janjouketjalsma and @quocanha,

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

ashish3805 commented 2 weeks ago

+1 I am facing this issue as well