In springdocs, can I define multiple OpenAPI definitions based on tags on the operations - springdoc

Question

I need to define two different OpenApi definitions using springdocs for the same API within a single application: one for internal developers and one for external developers. The external definition would include some of the operations from the internal definition, but not all of them.
I have looked at using GroupedOpenApi to create the two definitions, but this requires that I move the endpoints that should be excluded from the external definition into a separate RestController and move to an excluded package, which would not be included in the definition for the external developers, but would still be included in the internal definition. I would prefer to structure my code based on the API definition and not based on the security access for my endpoints.
This seems like either SecurityScheme or tags could be used to define which operations are included in a given definition using something like GroupedOpenApi with the paths/packages to include. So for example, I could define the definition for my external API with something like the following:
GroupedOpenApi.builder()
.group("externalGroupName")
.securitySchemesToInclude("externalSchemeName") // this doesn't currently exist
.build();
And then any of the operations that are tagged with a SecurityRequirement with that SecurityScheme would get added to this external definition. So for example I could have the following two endpoints defined within the same RestController:
Would be included:
#SecurityRequirement(name = "externalSchemeName")
#GET
#Path("/pets")
public Response getResponse(){
return null;
}
}
Would not be included:
#SecurityRequirement(name = "internalSchemeName")
#GET
#Path("/pets/internal")
public Response getInternalResponse(){
return null;
}
}
With this approach, it would be nice to provide for include/excluded security schemes similar to paths/package inclusions/exclusions.
This seems like it would currently require a contribution to springdocs unless I am misunderstanding my options for how to create multiple definitions. Is there another way to achieve excluding an operation from only one of the definitions I define without completely hiding that operation from all definitions and without restructuring my packages?
Note that I also would prefer not to maintain a list of all the paths that should be excluded from the group in config if possible as this is error prone and doesn't allow for providing a shared config across multiple services. I would prefer an annotation-driven method similar to the way other swagger customization is done so that I define the config once and then update each resource as it is defined or modified based on an annotation to drive the swagger that is generated.

Answer 1

Using you example, you have other filters (based on paths) of GroupedOpenApi, that you haven't used:
GroupedOpenApi.builder()
.group("internalGroupName")
.pathsToMatch("/pets/internal")
.build();
GroupedOpenApi.builder()
.group("externalGroupName")
.pathsToMatch("/pets")
.packagesToExclude("/pets/internal")
.build();