Merge pull request #830 from dsmf/chore/639-improve-documentation

chore(documentation): [#639] improve documentation
eclipse-tractusx · Jul 23, 2024 · c993202 · c993202
2 parents a9de0bf + a99eb75
commit c993202
Show file tree

Hide file tree

Showing 3 changed files with 49 additions and 24 deletions.
diff --git 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.4.0] - 2024-07-22
 
 ### Changed

diff --git 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=<property>,[EQUALS|STARTS_WITH|BEFORE_LOCAL_DATE|AFTER_LOCAL_DATE],<value>`.
-          Example: `search=BPN,STARTS_WITH,BPNL12&search=policyId,STARTS_WITH,policy2`.
-
-        - **Sorting:**
-          `sort=<property>,[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=<Field>,[EQUALS|STARTS_WITH|BEFORE_LOCAL_DATE|AFTER_LOCAL_DATE],<Value>`.\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/...src/main/java/org/eclipse/tractusx/irs/policystore/controllers/PolicyStoreController.java b/...src/main/java/org/eclipse/tractusx/irs/policystore/controllers/PolicyStoreController.java
@@ -262,20 +262,38 @@ public List<String> 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=<Field>,[EQUALS|STARTS_WITH|BEFORE_LOCAL_DATE|AFTER_LOCAL_DATE],<Value>`.
+                       \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=<property>,[EQUALS|STARTS_WITH|BEFORE_LOCAL_DATE|AFTER_LOCAL_DATE],<value>`.
-                         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=<property>,[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 }, //