OpenAPI GET /v1/component/project/{uuid} return value incorrect

[esnible]

Current Behavior

The OpenAPI definition promises an array of #/definitions/Component. The returned values don't look like the Component definition. They lack fields such as sha256 and include fields such as repositoryMeta.

See DependencyTrack/client-go#26 and #2604

Steps to Reproduce

1. curl -v -H "X-API-Key: $DT_API_KEY" -H "Accept: application/json" localhost:8080/api/v1/component/project/$MY_PROJ_UUD | jq ".[0] | keys"

Expected Behavior

I would like to know if the current value is intended and I may use it in scripts. If so, I would like curl mydt:8080/api/swagger.json to return the schema of the data.

Dependency-Track Version

4.10.1

Dependency-Track Distribution

Container Image

Database Server

N/A

Database Server Version

No response

Browser

N/A

Checklist

• I have read and understand the contributing guidelines
• I have checked the existing issues for whether this defect was already reported

[esnible]

Also note that this API seems to respect ?offset= but not limit= or page=.

[nscuro]

That not all fields are returned for every API endpoint is kind of intended. Component has lots of fields, some of them are large themselves (e.g. directDependencies). Listing components of a project thus becomes expensive, due to network and serialization cost alone.

Ideally, listing many components would only yield surface-level fields such as identifiers. For more details, each component would need to be requested explicitly (or in bulk by providing multiple UUIDs for example).

I do agree that the API spec needs to make such behavior clear though. The fact that it doesn't is a symptom of reusing the same model classes across all endpoints.

Also note that this API seems to respect ?offset= but not limit= or page=.

Also agree. The reason those are currently not part of the OpenAPI spec, is that they are implicit, and not every endpoint has explicit definitions for them. The good news is that this is easily solvable for us using the ApiImplicitParam annotation.

There are multiple improvements towards the OpenAPI spec coming in v4.11, I might be able to squeeze that in as well. It's literally just copy-pasting annotations hopefully.

[nscuro]

Sorry, misread what you meant with:

Also note that this API seems to respect ?offset= but not limit= or page=.

I think the parameters you're looking for are pageNumber and pageSize. Those are used by the frontend as well, it is what enables the paging in the Project -> Components tab.

This kind of alludes to what I mentioned in my answer above: The pagination parameters are missing from the OpenAPI spec.

[nscuro]

Documentation for pagination parameters is coming with #3625.