docs: iam oas improvement

hyperledger · May 3, 2024 · 9ccaf99 · 9ccaf99
1 parent eeb8a4d
commit 9ccaf99
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 11 deletions.
diff --git a/...t/service/server/src/main/scala/org/hyperledger/identus/agent/server/http/DocModels.scala b/...t/service/server/src/main/scala/org/hyperledger/identus/agent/server/http/DocModels.scala
@@ -3,6 +3,7 @@ package org.hyperledger.identus.agent.server.http
 import org.hyperledger.identus.castor.controller.{DIDEndpoints, DIDRegistrarEndpoints}
 import org.hyperledger.identus.connect.controller.ConnectionEndpoints
 import org.hyperledger.identus.event.controller.EventEndpoints
+import org.hyperledger.identus.iam.entity.http.EntityEndpoints
 import org.hyperledger.identus.iam.wallet.http.WalletManagementEndpoints
 import org.hyperledger.identus.issue.controller.IssueEndpoints
 import org.hyperledger.identus.pollux.credentialdefinition.CredentialDefinitionRegistryEndpoints
@@ -117,7 +118,8 @@ object DocModels {
           DIDRegistrarEndpoints.tag,
           WalletManagementEndpoints.tag,
           SystemEndpoints.tag,
-          EventEndpoints.tag
+          EventEndpoints.tag,
+          EntityEndpoints.tag
         )
       )
 

diff --git a/...rvice/server/src/main/scala/org/hyperledger/identus/event/controller/EventEndpoints.scala b/...rvice/server/src/main/scala/org/hyperledger/identus/event/controller/EventEndpoints.scala
@@ -22,8 +22,7 @@ object EventEndpoints {
 
   private val tagName = "Events"
   private val tagDescription =
-    s"""
-       |The __${tagName}__ endpoints enable users to manage event-related resources, such as webhook notifications.
+    s"""The __${tagName}__ endpoints enable users to manage event-related resources, such as webhook notifications.
        |These notifications are specifically designed to inform about events occurring within the wallet, including but not limited to:
        |
        |- DID publication notifications

diff --git a/...rvice/server/src/main/scala/org/hyperledger/identus/iam/entity/http/EntityEndpoints.scala b/...rvice/server/src/main/scala/org/hyperledger/identus/iam/entity/http/EntityEndpoints.scala
@@ -8,6 +8,7 @@ import org.hyperledger.identus.iam.authentication.admin.AdminApiKeySecurityLogic
 import org.hyperledger.identus.iam.authentication.oidc.JwtCredentials
 import org.hyperledger.identus.iam.authentication.oidc.JwtSecurityLogic.jwtAuthHeader
 import org.hyperledger.identus.iam.entity.http.model.*
+import sttp.apispec.Tag
 import sttp.model.StatusCode
 import sttp.tapir.json.zio.jsonBody
 import sttp.tapir.{Endpoint, EndpointInput, endpoint, extractFromRequest, path, query, statusCode, stringToPath}
@@ -16,6 +17,22 @@ import java.util.UUID
 
 object EntityEndpoints {
 
+  private val tagName = "Identity and Access Management"
+  private val tagDescription =
+    s"""
+       |The __${tagName}__ endpoints allow [agent administrators](https://docs.atalaprism.io/docs/concepts/glossary#administrator)
+       |to manage identity and access management for the agent's tenants.
+       |It provides basic IAM capabilities as an alternative to more feature rich external IAM solutions.
+       |
+       |Entities are resources that represent individual tenants and
+       |wallets act as containers for Self-Sovereign Identity (SSI) resources within the agent.
+       |The administrator can grant tenant access to specific wallets by associating the wallet ID with the Entity.
+       |Additionally, the administrator can create API keys for entities and provide them to the tenants out-of-band.
+       |These API keys can then be used for authorization to access specific wallets.
+       |""".stripMargin
+
+  val tag = Tag(tagName, Some(tagDescription))
+
   val createEntityEndpoint: Endpoint[
     (AdminApiKeyCredentials, JwtCredentials),
     (RequestContext, CreateEntityRequest),
@@ -48,7 +65,7 @@ object EntityEndpoints {
       .description(
         "Create the new entity record. The entity record is a representation of the account in the system."
       )
-      .tag("Identity and Access Management")
+      .tag(tagName)
 
   val updateEntityNameEndpoint: Endpoint[
     (AdminApiKeyCredentials, JwtCredentials),
@@ -84,7 +101,7 @@ object EntityEndpoints {
       .description(
         "Update the entity record name by `id`"
       )
-      .tag("Identity and Access Management")
+      .tag(tagName)
 
   val updateEntityWalletIdEndpoint: Endpoint[
     (AdminApiKeyCredentials, JwtCredentials),
@@ -120,7 +137,7 @@ object EntityEndpoints {
       .description(
         "Update the entity record `walletId` field by `id`"
       )
-      .tag("Identity and Access Management")
+      .tag(tagName)
 
   val getEntityByIdEndpoint: Endpoint[
     (AdminApiKeyCredentials, JwtCredentials),
@@ -145,7 +162,7 @@ object EntityEndpoints {
       .description(
         "Get the entity by the unique identifier"
       )
-      .tag("Identity and Access Management")
+      .tag(tagName)
 
   private val paginationInput: EndpointInput[PaginationInput] = EndpointInput.derived[PaginationInput]
   val getEntitiesEndpoint: Endpoint[
@@ -171,7 +188,7 @@ object EntityEndpoints {
       .description(
         "Get all entities with the pagination by `offset` and `limit` parameters "
       )
-      .tag("Identity and Access Management")
+      .tag(tagName)
 
   val deleteEntityByIdEndpoint: Endpoint[
     (AdminApiKeyCredentials, JwtCredentials),
@@ -198,7 +215,7 @@ object EntityEndpoints {
       .description(
         "Delete the entity by the unique identifier"
       )
-      .tag("Identity and Access Management")
+      .tag(tagName)
 
   val addEntityApiKeyAuthenticationEndpoint: Endpoint[
     (AdminApiKeyCredentials, JwtCredentials),
@@ -229,7 +246,7 @@ object EntityEndpoints {
     .description(
       "Register the `apikey` for the entity."
     )
-    .tag("Identity and Access Management")
+    .tag(tagName)
 
   val deleteEntityApiKeyAuthenticationEndpoint: Endpoint[
     (AdminApiKeyCredentials, JwtCredentials),
@@ -260,5 +277,5 @@ object EntityEndpoints {
     .description(
       "Unregister the `apikey` for the entity."
     )
-    .tag("Identity and Access Management")
+    .tag(tagName)
 }