OpenAPI GET /v1/component/project/{uuid} return value incorrect
esnible opened this issue · comments
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
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
Also note that this API seems to respect ?offset= but not limit= or page=.
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.
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.