Api with @Operation on @RepositoryRestController are not registered

[speralta]

Describe the bug
Using spring-data-rest, we need to use specific controllers annotated with @RepositoryRestController to define some API. Methods in those specific controllers are not added to generated documentation.

I try to add @Operation on method as recommended on issue #263 unsuccesfully.
Not sure if it's a bug or if I'm missing something.

To Reproduce
Steps to reproduce the behavior:

• What version of spring-boot you are using?
  2.4.2
• What modules and versions of springdoc-openapi are you using?
  1.5.3
• What is the actual and the expected result using OpenAPI Description (yml or json)?
  Actual :

  "openapi": "3.0.1",
  "info": {
    "title": "Test API",
    "description": "Endpoints documentation",
    "version": "0.0.1"
  },
  "servers": [
    {
      "url": "http://localhost:8080/",
      "description": "Generated server url"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/domains": {
      "get": {
        "tags": [
          "domain-entity-controller"
        ],
        "description": "get-domain",
        "operationId": "getCollectionResource-domain-get_1",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Zero-based page index (0..N)",
            "required": false,
            "schema": {
              "minimum": 0,
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "The size of the page to be returned",
            "required": false,
            "schema": {
              "minimum": 1,
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionModelDomain"
                }
              },
              "application/x-spring-data-compact+json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionModelDomain"
                }
              },
              "text/uri-list": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionModelDomain"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "domain-entity-controller"
        ],
        "description": "create-domain",
        "operationId": "postCollectionResource-domain-post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Domain"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/RepresentationModelDomain"
                }
              }
            }
          }
        }
      }
    },
    "/domains/{id}": {
      "get": {
        "tags": [
          "domain-entity-controller"
        ],
        "description": "get-domain",
        "operationId": "getItemResource-domain-get",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityModelDomain"
                }
              }
            }
          },
          "404": {
            "description": "Not Found"
          }
        }
      },
      "put": {
        "tags": [
          "domain-entity-controller"
        ],
        "description": "update-domain",
        "operationId": "putItemResource-domain-put",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Domain"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/RepresentationModelDomain"
                }
              }
            }
          },
          "201": {
            "description": "Created",
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/RepresentationModelDomain"
                }
              }
            }
          },
          "204": {
            "description": "No Content"
          }
        }
      },
      "delete": {
        "tags": [
          "domain-entity-controller"
        ],
        "description": "delete-domain",
        "operationId": "deleteItemResource-domain-delete",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "404": {
            "description": "Not Found"
          }
        }
      },
      "patch": {
        "tags": [
          "domain-entity-controller"
        ],
        "description": "patch-domain",
        "operationId": "patchItemResource-domain-patch",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Domain"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/RepresentationModelDomain"
                }
              }
            }
          },
          "204": {
            "description": "No Content"
          }
        }
      }
    },
    "/profile": {
      "get": {
        "tags": [
          "profile-controller"
        ],
        "operationId": "listAllFormsOfMetadata",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/RepresentationModelObject"
                }
              }
            }
          }
        }
      }
    },
    "/profile/domains": {
      "get": {
        "tags": [
          "profile-controller"
        ],
        "operationId": "descriptor_1",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "type": "string"
                }
              },
              "application/alps+json": {
                "schema": {
                  "type": "string"
                }
              },
              "application/schema+json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonSchema"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AbstractJsonSchemaPropertyObject": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "readOnly": {
            "type": "boolean"
          }
        }
      },
      "Item": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "properties": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/AbstractJsonSchemaPropertyObject"
            }
          },
          "requiredProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "JsonSchema": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "properties": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/AbstractJsonSchemaPropertyObject"
            }
          },
          "requiredProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "definitions": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/Item"
            }
          },
          "type": {
            "type": "string"
          },
          "$schema": {
            "type": "string"
          }
        }
      },
      "Links": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/Link"
        }
      },
      "RepresentationModelObject": {
        "type": "object",
        "properties": {
          "_links": {
            "$ref": "#/components/schemas/Links"
          }
        }
      },
      "Domain": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "field": {
            "type": "string"
          }
        }
      },
      "RepresentationModelDomain": {
        "type": "object",
        "properties": {
          "_links": {
            "$ref": "#/components/schemas/Links"
          }
        }
      },
      "EntityModelDomain": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "field": {
            "type": "string"
          },
          "_links": {
            "$ref": "#/components/schemas/Links"
          }
        }
      },
      "CollectionModelDomain": {
        "type": "object",
        "properties": {
          "_embedded": {
            "type": "object",
            "properties": {
              "domains": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Domain"
                }
              }
            }
          },
          "_links": {
            "$ref": "#/components/schemas/Links"
          }
        }
      },
      "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"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "UUID"
      }
    }
  }
}

• Provide with a sample code (HelloController) or Test that reproduces the problem
  Minimal project to reproduce : https://github.com/speralta/springdoc-repositoryrestcontroller
  API defined https://github.com/speralta/springdoc-repositoryrestcontroller/blob/e9da311a6bf3d77fb795d2352740ddc4b97277a3/src/main/java/test/api/DomainApi.java#L15
  is not in the OpenAPI Description.

Expected behavior

• A clear and concise description of what you expected to happen.
  A new PathItem corresponding to "/domain/test".
• What is the expected result using OpenAPI Description (yml or json)?

...
  "/domains/test": {
      "get": {
        "operationId": "test-get",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityModelDomain"
                }
              }
            }
          }
        }
      },
      ...

Additional context
The springdoc-openapi-data-rest registers the @RepositoryRestResource without issue.

[bnasslahsen]

@speralta,

For your endpoint, you could simply use @RestController or @Controller to register it as rest endpoint, which are the standard annotations for this usage.

@RepositoryRestController is generally used for registering repositories. Using it instead of the above
annotations is just an unusual usage, and is not a priority to be supported.

Using @RepositoryRestController on the controller level might have some unwanted behaviors, like the open session in view anti-pattern.

I wish my answer helps you better designing your application.

[speralta]

It's not about @RepositoryRestResource : this annotation is for repository classes. It's about @RepositoryRestController (or @BasePathAwareController)

I can't use @RestController or @Controller, because the context is not the same. See https://docs.spring.io/spring-data/rest/docs/current/reference/html/#customizing-sdr.overriding-sdr-response-handlers

[bnasslahsen]

I have updated the annotation name. The same answer applies ...
Maybe you could propose a PR for this support?

[speralta]

I can try. Could you point me in the right direction ?

[bnasslahsen]

@speralta,

You have springdoc-openapi-data-rest module, which is responsible of scanning of the spring-data-rest controllers.

The difference of spring-data-rest controller with the other spring-mvc/webflux/hateoas is that in general, the controllers are resolved dynamically at the request time, not during the spring context initialization.

I would presume, you will need to apply the same logic as for @RepositoryRestResource, unless you find out a smarter way.

You have some guidance, for code formatting and building the project in local, in the contribution guide.

If you have any other questions, please feel free to ask.