DependencyTrack
Migrate Swagger to OpenAPI 3
The current swagger definition is autogenerated. The automatically generated definitions rely on reflection and annotations to create the documentation. The reflection capabilities are poor at best and lead to missing API parameters. Annotations can help in some cases, but the only fix for Swagger is to create individual POJOs for every possible request. This will lead to unnecessary large number of classes and affects on GC.
Therefore, in order to migrate to OpenAPI 3 and have to deal with similar issues (the Java implementations are virtually the same), the only way to accurately describe the API is to manually keep it updated.
This ticket is to track the removal of Swagger from Alpine and from Dependency-Track and to include support for OpenAPI 3 definitions that can be authored and improved by the community over time.
Related to https://github.com/stevespringett/Alpine/issues/1
You can import the current swagger.json and convert it to openapi.yml using https://editor.swagger.io/, so you do not have to start from scratch. This site is also a good starting point for writing openapi.yml files. I have made good experiences with it.
FWIW, creating pojos for every request isn't strictly necessary, mainly only the Create/Update requests which don't accept all parameters (i.e. trying to pass uuid in on create project when it gets ignored).
I think I posted this in Slack a while back already, but another good approach we can take is to generate resource definitions (read: interfaces with all sorts of validation annotations) and DTOs from the openapi YAML. The generator for jaxrs-spec could work.
That way the YAML will be the single source of truth. We get syntactic validation for free in many cases, and because we have to implement interfaces we can be sure our code matches what we advertise.
There will be additional work in mapping between persistent models and DTOs, but that can be a benefit. Due to DataNucleus fetching some properties lazily, they are sometimes missing in API responses, even though they should be there. We won't have that issue if we explicitly map our types.
Moving to a later milestone. FTR, this issue is intertwined with the migration from Java EE to Jakarta EE namespaces, which includes an upgrade of Jersey and Jetty. The current proposed way forward is documented here: https://github.com/stevespringett/Alpine/issues/402#issuecomment-1593407468