doc: improve openapi for authorization endpoint

eclipse-kapua · Mar 4, 2025 · a753097 · a753097
1 parent 41055ab
commit a753097
Show file tree

Hide file tree

Showing 2 changed files with 49 additions and 11 deletions.
diff --git a/rest-api/resources/src/main/resources/openapi/authorization/authorization-scopeId.yaml b/rest-api/resources/src/main/resources/openapi/authorization/authorization-scopeId.yaml
@@ -26,14 +26,12 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  type: string
-    400:
-      $ref: '../openapi.yaml#/components/responses/illegalArgument'
-      401:
-        $ref: '../openapi.yaml#/components/responses/unauthenticated'
-      403:
-        $ref: '../openapi.yaml#/components/responses/subjectUnauthorized'
-      500:
-        $ref: '../openapi.yaml#/components/responses/kapuaError'
+                $ref: './authorization.yaml#/components/schemas/claimListResult'
+        400:
+          $ref: '../openapi.yaml#/components/responses/illegalArgument'
+        401:
+          $ref: '../openapi.yaml#/components/responses/unauthenticated'
+        403:
+          $ref: '../openapi.yaml#/components/responses/subjectUnauthorized'
+        500:
+          $ref: '../openapi.yaml#/components/responses/kapuaError'
diff --git a/rest-api/resources/src/main/resources/openapi/authorization/authorization.yaml b/rest-api/resources/src/main/resources/openapi/authorization/authorization.yaml
@@ -0,0 +1,40 @@
+openapi: 3.0.3
+
+info:
+  title: Eclipse Kapua REST API - Authorizations
+  version: '1.0'
+  contact:
+    name: Eclipse Kapua Dev Team
+    url: https://eclipse.org/kapua
+    email: kapua-dev@eclipse.org
+  license:
+    name: Eclipse Public License 2.0
+    url: https://www.eclipse.org/legal/epl-2.0
+
+paths: {}
+
+components:
+  schemas:
+    claim:
+      type: string
+      description: Represent a user's claims, in the format `domain:action`.
+    claimListResult:
+      allOf:
+        - description: A container for a list of claim objects
+          type: object
+          properties:
+            items:
+              type: array
+              items:
+                $ref: '#/components/schemas/claim'
+          example:
+              - "job:read"
+              - "device_management_registry:write"
+              - "group:delete"
+              - "device_lifecycle:read"
+              - "certificate:read"
+              - "device_lifecycle:delete"
+              - "certificate:write"
+              - "credential:read"
+              - "event_store:write"
+              - "device:write"