From 865936f3415b162331a0f8934b74db73b61b6363 Mon Sep 17 00:00:00 2001 From: Matthias Fischer Date: Fri, 19 Jul 2024 13:51:52 +0200 Subject: [PATCH 1/2] chore(documentation): [#639] improve documentation - harmonize description of GET /irs/policies and /irs/policies/paged - describe supported attributes in filter and sort - document supported search operators and value format - document default and max page size --- docs/src/api/irs-api.yaml | 31 ++++++++------- .../controllers/PolicyStoreController.java | 38 ++++++++++++++----- 2 files changed, 45 insertions(+), 24 deletions(-) diff --git a/docs/src/api/irs-api.yaml b/docs/src/api/irs-api.yaml index fadd254c3..287cbc4bd 100644 --- a/docs/src/api/irs-api.yaml +++ b/docs/src/api/irs-api.yaml @@ -1042,19 +1042,21 @@ paths: - Policy Store API /irs/policies/paged: get: - description: | - Fetch a page of policies with options to filter and sort. - - - **Filtering:** - `search=,[EQUALS|STARTS_WITH|BEFORE_LOCAL_DATE|AFTER_LOCAL_DATE],`. - Example: `search=BPN,STARTS_WITH,BPNL12&search=policyId,STARTS_WITH,policy2`. - - - **Sorting:** - `sort=,[asc|desc]`. - Example: `sort=BPN,asc&sort=policyId,desc`. - - - **Paging:** - Example: `page=1&size=20` + description: "Fetch a page of policies with options to filter and sort.\n \n\ + Example:\n```\nsearch=BPN,STARTS_WITH,BPNL12&search=validUntil,AFTER_LOCAL_DATE,2024-12-11&sort=validUntil,asc&sort=BPN,asc\n\ + ```\n \n### Filtering\n \n`search=,[EQUALS|STARTS_WITH|BEFORE_LOCAL_DATE|AFTER_LOCAL_DATE],`.\n\ + \ \nExample: `search=BPN,STARTS_WITH,BPNL12&search=policyId,STARTS_WITH,policy2`.\n\ + \ \n| Field | Supported Operations | Value Format\ + \ |\n|--------------|------------------------------------------|----------------------|\n\ + | `BPN` | `EQUALS`, `STARTS_WITH` | any string \ + \ |\n| `policyId` | `EQUALS`, `STARTS_WITH` | any\ + \ string |\n| `action` | `EQUALS` \ + \ | `use` or `access` |\n| `createdOn` | `BEFORE_LOCAL_DATE`, `AFTER_LOCAL_DATE`\ + \ | `yyyy-MM-dd` |\n| `validUntil` | `BEFORE_LOCAL_DATE`, `AFTER_LOCAL_DATE`\ + \ | `yyyy-MM-dd` |\n\n### Sorting\n`sort=[BPN|policyId|action|createdOn|validUntil],[asc|desc]`.\n\ + \ \nExample: `sort=BPN,asc&sort=policyId,desc`. _(default: `BPN,asc`)_\n\n\ + ### Paging\n \nExample: `page=1&size=20` _(default page size: 10, maximal\ + \ page size: 1000)_\n" operationId: getPoliciesPaged parameters: - description: List of business partner numbers. This may also contain the value @@ -1096,7 +1098,8 @@ paths: description: Authorization refused by server. security: - api_key: [] - summary: Find policies. + summary: "Find registered policies that should be accepted in EDC negotiation\ + \ (with filtering, sorting and paging)." tags: - Policy Store API /irs/policies/{policyId}: diff --git a/irs-policy-store/src/main/java/org/eclipse/tractusx/irs/policystore/controllers/PolicyStoreController.java b/irs-policy-store/src/main/java/org/eclipse/tractusx/irs/policystore/controllers/PolicyStoreController.java index 62384f48f..beb077c6a 100644 --- a/irs-policy-store/src/main/java/org/eclipse/tractusx/irs/policystore/controllers/PolicyStoreController.java +++ b/irs-policy-store/src/main/java/org/eclipse/tractusx/irs/policystore/controllers/PolicyStoreController.java @@ -262,20 +262,38 @@ public List autocomplete( @GetMapping("/policies/paged") @ResponseStatus(HttpStatus.OK) - @Operation(summary = "Find policies.", // + @Operation(summary = "Find registered policies that should be accepted in EDC negotiation " + + "(with filtering, sorting and paging).", // description = """ Fetch a page of policies with options to filter and sort. + \s + Example: + ``` + search=BPN,STARTS_WITH,BPNL12&search=validUntil,AFTER_LOCAL_DATE,2024-12-11&sort=validUntil,asc&sort=BPN,asc + ``` + \s + ### Filtering + \s + `search=,[EQUALS|STARTS_WITH|BEFORE_LOCAL_DATE|AFTER_LOCAL_DATE],`. + \s + Example: `search=BPN,STARTS_WITH,BPNL12&search=policyId,STARTS_WITH,policy2`. + \s + | Field | Supported Operations | Value Format | + |--------------|------------------------------------------|----------------------| + | `BPN` | `EQUALS`, `STARTS_WITH` | any string | + | `policyId` | `EQUALS`, `STARTS_WITH` | any string | + | `action` | `EQUALS` | `use` or `access` | + | `createdOn` | `BEFORE_LOCAL_DATE`, `AFTER_LOCAL_DATE` | `yyyy-MM-dd` | + | `validUntil` | `BEFORE_LOCAL_DATE`, `AFTER_LOCAL_DATE` | `yyyy-MM-dd` | - - **Filtering:** - `search=,[EQUALS|STARTS_WITH|BEFORE_LOCAL_DATE|AFTER_LOCAL_DATE],`. - Example: `search=BPN,STARTS_WITH,BPNL12&search=policyId,STARTS_WITH,policy2`. + ### Sorting + `sort=[BPN|policyId|action|createdOn|validUntil],[asc|desc]`. + \s + Example: `sort=BPN,asc&sort=policyId,desc`. _(default: `BPN,asc`)_ - - **Sorting:** - `sort=,[asc|desc]`. - Example: `sort=BPN,asc&sort=policyId,desc`. - - - **Paging:** - Example: `page=1&size=20` + ### Paging + \s + Example: `page=1&size=20` _(default page size: 10, maximal page size: 1000)_ """, // security = @SecurityRequirement(name = API_KEY), // tags = { POLICY_API_TAG }, // From 6870d01c94a766e8b6dc0f77c952f90168d53897 Mon Sep 17 00:00:00 2001 From: Matthias Fischer Date: Fri, 19 Jul 2024 14:41:55 +0200 Subject: [PATCH 2/2] chore(documentation): [#639] update changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 58c6ec2c0..0bca8a354 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ _**For better traceability add the corresponding GitHub issue number in each cha ## [Unreleased] +### Changed + +- Improved documentation for `GET /irs/policies/paged` endpoint. #639 + ## [5.3.0] - 2024-07-15 ### Added