Programmatic customization of the OpenAPI, problem with GroupedOpenApi?!

The docs state that programmatic customization of the OpenAPI object is supported:

@Bean
public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
  return new OpenAPI()
  .components(new Components().addSecuritySchemes("basicScheme",
          new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")))
  .info(new Info().title("SpringShop API").version(appVersion)
          .license(new License().name("Apache 2.0").url("http://springdoc.org")));
}

Is it supported / allowed to add parts of the API spec here programmatically (paths)? Something like this:

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .path("/foo",
                        new PathItem().get(new Operation().operationId("foo").responses(new ApiResponses()
                                .addApiResponse("default",
                                        new ApiResponse()
                                                .description("")
                                                .content(new Content().addMediaType("fatz", new MediaType()))))));
    }

Use case might be if some generic endpoints exists and someone prefers to add the spec programmatically instead of adding hunderts of swagger annotations to the controller. Or also someone has written the Open API spec by hand and wants to include it even before he actually implemented it (load from file, parse, add to object).

If it is supported / allowed, it currently causes a bug when using it at the same time with the GroupedOpenApi feature. The definitions added to the OpenAPI object appear within every group-endpoint-response, no matter if they fullfill the conditions specified on the GroupedOpenApi or not.

If it is NOT supported / allowed, maybe there should be a comment in the docs about it?!

[bnasslahsen]

Hi @kaibra,

Maybe we need to add more explanation on the documentation about this behaviour your are describing.

If you need the defintions to appear globally (withing every group), no matter if the group fulfills the conditions specified on the GroupedOpenApi , you can use OpenAPI Bean.

@Bean
public OpenAPI customOpenAPI() {
	return new OpenAPI().path("/foo",
	new PathItem().get(new Operation().operationId("foo").responses(new ApiResponses()
	.addApiResponse("default",new ApiResponse()description("")
	content(new Content().addMediaType("fatz", new MediaType()))))));
}

If you need the defintions to appear withing a specific group, and respect the conditions specified on the GroupedOpenApi, you can add OpenApiCustomiser to your GroupedOpenApi definition.

GroupedOpenApi.builder().setGroup("users").pathsToMatch(paths).packagesToScan(packagedToMatch).addOpenApiCustomiser(customerGlobalHeaderOpenApiCustomiser())
                .build()

@Bean
public OpenApiCustomiser customerGlobalHeaderOpenApiCustomiser() {
	return openApi -> openApi.path("/foo",
	new PathItem().get(new Operation().operationId("foo").responses(new ApiResponses()
	.addApiResponse("default",new ApiResponse().description("")
	.content(new Content().addMediaType("fatz", new MediaType()))))));
}

This should answer to boths usages. Please let me know if its ok for you.

[bnasslahsen]

Hi @kaibra,

Sorry I haven’t seen your message. You can of course propose a PR, which integrates this functionality, so we can enhance the library. It would have more sense in separate maven module: springdoc-openapi-swagger-parser. We can add on the class GroupConfig, the property staticSpecLocation.