eclipse-tractusx / eclipse-tractusx/bpdm

Pool: Document V7 Participants Endpoints

Open
#1,685 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.