search

openapi-tools / swagger-maven-plugin

Maven plugin to activate the Swagger Core library to generate OpenAPI documentation.
MIT License
72 stars 46 forks source link

Allow to set Swagger scanner class #27

Open tosix1988 opened 5 years ago

tosix1988 commented 5 years ago

In Swagger JAX-RS configuration, it is possible to set which type of resource scanner should be used to scan resources by specifying the "scannerClass" parameter of openapi-configuration. Either one of pre-defined ones can be used, or one can implement its own custom scanner implementing the OpenApiScanner interface.

The difference in the generated OpenAPI specification can be seen e.g. by using the sample project: swagger-maven-plugin-sample-project-scanner.zip. The project uses io.swagger.v3.jaxrs2.integration.JaxrsApplicationScanner, and so the generated OpenAPI specification contains only the resources defined by the RestApplication class; the plugin scans all @Path annotated endpoints, and thus produces different specification.

Do you think it would be a useful feature of the plugin to support?

langecode commented 5 years ago

Sounds reasonable to support - if there is a demand for it. But from an architecture perspective it would allow for removing some code from the plugin basing it on Swagger instead - which from my perspective would be nice.

It seems like the JaxrsOpenApiScanner might be useful also for the plugin. I think the reason for not using this already was that being outside of the normal runtime environment I am not sure the JAX-RS Application class can be correctly initialized - depending on what the scanner is using the application for. If the scanner implementation is invoking getSingletons() and getClasses() this may fail running in a plugin without the proper runtime environment.

tosix1988 commented 5 years ago

I see your point.

I would propose something along these lines: By default, the plugin could use io.swagger.v3.jaxrs2.integration.JaxrsAnnotationScanner to scan for resources. There should be no Application#getClasses() involved, so this should be safe in any scenario, and should work similarly as the plugin works now (if not exactly the same, I haven't checked thoroughly). However, it would be allowed to set the scanner class to use by specifying "scannerClass" parameter. So that in cases where, for example, you need to use only resources from Application class and you know that calling Application#getClasses() is safe, you could specify io.swagger.v3.jaxrs2.integration.JaxrsApplicationScanner as the scanner class, and the plugin would generate the same output as the swagger-jaxrs would actually generate if it would be configured with such scanner class. Instantiating the Application class should be safe, as the JAX-RS makes the constructor injection of Application classes optional and non-portable feature.