Migrate Swagger to OpenAPI 3

[stevespringett]

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 stevespringett/Alpine#1

[sephiroth-j]

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.

[ruckc]

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).

[nscuro]

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.

[nscuro]

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: stevespringett/Alpine#402 (comment)

[nscuro]

We are migrating to OpenAPI v3 via #3726. This issue will remain open however, since the goal of manually maintaining the OpenAPI spec is still to be done.

[jmezach]

I just pulled the OpenAPI v3 document from a the snapshot version running locally using docker-compose and it seems that there is just one small issue with it making the document invalid:

Errors:
        - attribute paths.'/version'(get).responses.200.description is missing

Thought I'd post that here :).

[nscuro]

Thanks @jmezach, will be fixed in stevespringett/Alpine#631

I seem to have encountered this as well while migrating the DT code base, but chose to ignore it back then just so I can proceed with said migration:

dependency-track/src/test/java/org/dependencytrack/resources/OpenApiResourceTest.java

Lines 56 to 59 in c63745b

	final List<String> validationMessages = parseResult.getMessages();
	// Version resource is defined in Alpine and outside our control.
	validationMessages.removeIf("attribute paths.'/version'(get).responses.200.description is missing"::equals);
	assertThat(validationMessages).isEmpty();

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.