eclipse-tractusx / eclipse-tractusx/bpdm
Pool: Document V7 Participants Endpoints
- Dominant language
- Kotlin
- Stars
- 12
- Forks
- 28
- Avg merge
- 3d 14h
- Merged PRs (30d)
- 41
Description
### Description
**As** a conformity assessor evaluating CX-0012 compliance,
**I want** the required `POST /participants/*/search` and `POST /participants/changelog/search` endpoints to be fully documented with OpenAPI annotations,
**so that** the generated OpenAPI specification includes these normative resources and satisfies the conformity proof requirement of CX-0012 §1.3.
CX-0012 §2.2.1 requires the following endpoints to be implemented and included in the OpenAPI specification:
- `POST /participants/legal-entities/search`
- `POST /participants/sites/search`
- `POST /participants/addresses/search`
- `POST /participants/changelog/search`
These endpoints exist and are functionally correct in `PoolMembersApi`, but none of them carry `@Operation` or `@ApiResponses` annotations. Their non-participant counterparts in `PoolLegalEntityApi`, `PoolSiteApi`, `PoolAddressApi`, and `PoolChangelogApi` all have complete Swagger documentation. The asymmetry means the generated OpenAPI spec does not properly describe these required resources, leaving the conformity proof incomplete.
### Acceptance Criteria
- [ ] `PoolMembersApi.searchLegalEntities` has an `@Operation` annotation with a summary and description matching the standard: *"Returns only legal entities by an array of BPNL, which are owned by data space participants"*
- [ ] `PoolMembersApi.postSiteSearch` has an `@Operation` annotation with a summary and description matching the standard: *"Returns only sites by an array of BPNS and/or an array of corresponding BPNL, which are owned by data space participants"*
- [ ] `PoolMembersApi.searchAddresses` has an `@Operation` annotation with a summary and description matching the standard: *"Returns only addresses by an array of BPNA and/or an array of corresponding BPNS and/or an array of corresponding BPNL, which are owned by data space participants"*
- [ ] `PoolMembersApi.searchChangelogEntries` has an `@Operation` annotation with a summary and description matching the standard: *"Returns only changelog entries of legal entities, sites and addresses, which are owned by data space participants"*
- [ ] All four methods in `PoolMembersApi` include `@ApiResponses` with at least 200, 400, 401, 403, and 500 response codes
- [ ] The generated OpenAPI specification includes all four participant-scoped endpoints with proper request/response schema documentation
### Additional Information
Reference: CX-0012 §1.3 Conformance and Proof of Conformity; §2.2.1.1–2.2.1.6 API Endpoints & Resources.
The participant-scoped endpoints are the data-space-exposed read surface of the Pool API (via EDC data asset `cx-taxo:ReadAccessPoolForDataSpaceParticipant`). Proper OpenAPI documentation is especially important for these endpoints because they are the ones registered as data assets per §2.2.3.
Contributor guide
Assessment
This issue has not been assessed yet.