Spring Data Rest Documentation Question

[MiellyEllen]

Is your feature request related to a problem? Please describe.
Question about how to better document Spring Data Rest Repositories

Describe the solution you'd like
I would like to override the "entityname"-entity-controller, "entityname"-search-controller tags and exclude the property apis.

Describe alternatives you've considered
Is there a way to do this without a code change

Additional context
I'm an instructor for LinkedIn Learning.https://www.linkedin.com/learning/instructors/mary-ellen-bowman. I'd like to include a demo of springdocs in one of my courses. I have MVC Controllers and Spring Data Rest Repositories. The MVC Controllers are easy to assign documentation with @tag, but I cannot figure out how to document my Spring Data REST API's better than what is generated by default.

[bnasslahsen]

@MiellyEllen,

You can achieve your goal by using OpenApiCustomiser.
Here is a sample configuration Bean that you can adapt, depending on your needs:

@Component
public class OpenApiTagsCustomiser extends SpecFilter implements OpenApiCustomiser {
	@Override
	public void customise(OpenAPI openApi) {
		// remove the property reference controller
		openApi.getPaths().entrySet().removeIf(path -> path.getValue().readOperations().stream().anyMatch(
				operation -> operation.getTags().stream().anyMatch(tag -> tag.endsWith("property-reference-controller"))));
		// rename the operation tags
		openApi.getPaths().values().stream().flatMap(pathItem -> pathItem.readOperations().stream())
				.forEach(operation -> {
					String tagName = operation.getTags().get(0);
					// rename the entity-controller tags
					if (tagName.endsWith("entity-controller")) {
						String entityName = tagName.substring(0, tagName.length() - 18);
						String myTagValue = "my-entity-" + entityName;
						// Replace with the new tag value
						operation.getTags().set(0, myTagValue);
					}
					// rename the search-controller tags
					else if (tagName.endsWith("search-controller")) {
						String entityName = tagName.substring(0, tagName.length() - 18);
						String myTagValue = "my-search-" + entityName;
						// Replace with the new tag value
						operation.getTags().set(0, myTagValue);
					}
				});
		removeBrokenReferenceDefinitions(openApi);
	}
}

[MiellyEllen]

Thanks for the in-depth example.
The spring-docs video I'm adding to my course will only be about 7 minutes, and I only update my courses once a year.
I was hoping for something easy to demonstrate in application.properties, but seems like that's currently not possible.
But that's fine.
I was able to step through your code in a debugger and tinker with the existing properties to get me somewhat there to do a decent demonstration:
springdoc.pathsToMatch=/tours,/tours/,/tours/search/**,/tours//ratings/,/ratings/,/packages,/packages/search/**,/packages/*
springdoc.autoTagClasses=false

BTW, is property referencing really a thing in Spring Data Rest API's? I get that impression for the generated docs.
I have a Spring Data Restful repository for an api called /tours with an attribute called "title". When I hit /tours/1/title i get a 404 back.

I'd like to share the video with you when the course goes live in about a month. Are you on LinkedIn? Here's my LinkedIn page: https://www.linkedin.com/in/mebowman. And my teaching website https://MaryEllenTeaches.me

[bnasslahsen]

Hi @MiellyEllen,

In fact property referencing is part of spring data rest: Here is sample about it:

• https://www.baeldung.com/spring-data-rest-relationships

For the moment, it's generated by default for all entities on spring-data-rest.

But what would be suitable for the projects, is to generate it dynamically, depending on the entity has relationships: : This is the ongoing enhancement about it: #792

It should be hopefully improved with the next release v1.4.5. Where we will introduce also the ability to add @Tags and @SecurityRequirements annotation on the @Repository level, in order to override the default tags.

[bnasslahsen]

@MiellyEllen,

FYI, the version v1.4.5 is now released.
The support of spring-data-rest has been enhanced with this release.

[MiellyEllen]

Wow! Great improvement!
I already recorded the video with 1.4.4 a few days ago and was preparing to send the equipment back to LinkedIn, but will definitely re-record with these updates.
Was there a way to re-tag the "profile-controller", if not, no big deal.

[bnasslahsen]

In Fact, for your repositories you can use @Tag swagger annotation on top of the Repository:

• springdoc-openapi/springdoc-openapi-data-rest/src/test/java/test/org/springdoc/api/app16/AccountRepository.java

  Line 41 in a382dd3

  @Tag(name = "The account Repository")

  .

For the profile-controller, it can be renamed, if needed using OpenApiCustomiser :

@Bean
OpenApiCustomiser OpenApiTagsCustomiser() {
	return openApi -> openApi.getPaths().values().stream().flatMap(pathItem -> pathItem.readOperations().stream())
			.forEach(operation -> {
				String tagName = operation.getTags().get(0);
				// rename the profile-controller tag
				if ("profile-controller".equals(tagName)) {
					// Replace with the new tag value
					operation.getTags().set(0, "my-profile");
				}
			});
}

[MiellyEllen]

Yep, the first thing I did was add @tag. happy to see it work.
For my example I don't need the /profile api to confuse the learner, so I just excluded it.
Thanks for you help. I'll let you know when it's live. Probably in a month