search

openapi-tools / swagger-maven-plugin

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

Ability to use wildcards in resourcePackages #84

Closed harveycggit closed 3 years ago

harveycggit commented 3 years ago

Hi, thanks for this excellent plugin! I've tried using wildcards in the resourcePackages tag, is that supported? I seem to get null pointers no matter what I try. Note it works perfectly when I specify the exact package(s). Currently I use holon to generate swagger.yaml but it only does that when the app is up and running, and since my apps are behind an API gateway I have to briefly expose the app publicly during the jenkins build in order to get the yaml to feed the gateway, which is a security risk for me. So this is the perfect solution for me! However, populating the gateway is framework code and in my opinion something that the developers should not need to be concerned with, so ideally if they add a new REST API class, the services would just appear in the gateway during the next build without them having to configure additional packages in the build section of the pom. And the only solution I can see for that is allowing wildcards in the resources declaration:

    <resourcePackages>
      <resourcePackage>edu.upenn.isc.*</resourcePackage>
    </resourcePackages>

Please let me know if this would be possible and if you would be interested, I could attempt to contribute code if needed.

Best, Charles Harvey

langecode commented 3 years ago

I surely understand your use-case when we created the plugin we had pretty much the same need - to be able to create the OpenAPI/Swagger definition during build time instead of only having it at runtime.

However, I am not sure I understand how you would run the plugin. You want to push the configuration of the plugin upwards into a parent Maven pom or similar? Because you are right, currently the scanning for API classes does not recurse through the packages. I think this was a choice to let the user of the plugin have full control. If your service is generated, e.g., from an archetype you could generate the configuration as part of the archetype, however, if you want to push the configuration upwards you will need the recursive behaviour.

I guess, it would be quite ok to add an option whether to enable the recursion or not, if I remember correctly this takes place in the "scanner" implementation. You are more than welcome to do a PR for this feature.

harveycggit commented 3 years ago

Thank you for the quick response! I am not using an upstream pom; I have a template that is used for new projects where some automated search and replace goes on in the project templates, so the build plugin would exist for every project. My main interest is having this functionality be removed from the developers' stable of responsibilities; I don't have to train them and they make fewer mistakes. I'm using the generated swagger in a Jenkins pipeline to populate both 3scale (my API gateway) and SwaggerHub and would be happier if a developer was never in a situation where they added a new REST resource in a new package and were then puzzled by why they don't see it in SwaggerHub, etc. We work pretty hard here to keep developers writing code as opposed to worrying about configurations :)

I'll have a look and see if I can figure out how to change to scan all classes that are within the project's code given a syntax like:

edu.upenn.isc.*

there would be no need to scan any library jars, etc.

Thank you, I'll get back to you if I can figure it out. From your perspective, would you prefer an additional config property like true or would simply ending the resourcePackage with an asterisk be enough?

Best, Charles

harveycggit commented 3 years ago

Sorry it ate my examples. From your perspective, would you prefer an additional config property like <recursiveScan>true<recursiveScan> or would simply ending the resourcePackage with an asterisk be enough?

harveycggit commented 3 years ago

Ok, maybe I am confused, but the following setting seems to do exactly what I want to do, which is find @Api in every package under edu.upenn.isc.esb.openshiftUtils - does that seem correct?

<configuration> <useResourcePackagesChildren>true</useResourcePackagesChildren> <resourcePackages> <resourcePackage>edu.upenn.isc.esb.openshiftUtils</resourcePackage> </resourcePackages>

langecode commented 3 years ago

Yes you are right - we seem to have this feature already. If you enable userResourcePackagesChildren you should get recursive behaviour - implemented here: https://github.com/openapi-tools/swagger-maven-plugin/blob/master/src/main/java/io/openapitools/swagger/JaxRSScanner.java#L72

Been long since we did that code so I actually did not remember. Let me know if it does not work.