docs: improve OAS docs for Event and IAM section (#1007)

Signed-off-by: Pat Losoponkul <[email protected]> Co-authored-by: Yurii Shynbuiev - IOHK <[email protected]>
hyperledger · May 3, 2024 · cf156d9 · cf156d9
1 parent d8cca7e
commit cf156d9
Show file tree

Hide file tree

Showing 4 changed files with 75 additions and 15 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
@@ -2,7 +2,10 @@ 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
 import org.hyperledger.identus.pollux.credentialschema.{SchemaRegistryEndpoints, VerificationPolicyEndpoints}
 import org.hyperledger.identus.system.controller.SystemEndpoints
@@ -11,7 +14,6 @@ import sttp.apispec.{SecurityScheme, Tag}
 import sttp.model.headers.AuthenticationScheme
 
 import scala.collection.immutable.ListMap
-import org.hyperledger.identus.issue.controller.IssueEndpoints
 
 object DocModels {
 
@@ -115,7 +117,9 @@ object DocModels {
           DIDEndpoints.tag,
           DIDRegistrarEndpoints.tag,
           WalletManagementEndpoints.tag,
-          SystemEndpoints.tag
+          SystemEndpoints.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
@@ -11,6 +11,7 @@ import org.hyperledger.identus.iam.authentication.apikey.ApiKeyCredentials
 import org.hyperledger.identus.iam.authentication.apikey.ApiKeyEndpointSecurityLogic.apiKeyHeader
 import org.hyperledger.identus.iam.authentication.oidc.JwtCredentials
 import org.hyperledger.identus.iam.authentication.oidc.JwtSecurityLogic.jwtAuthHeader
+import sttp.apispec.Tag
 import sttp.model.StatusCode
 import sttp.tapir.*
 import sttp.tapir.json.zio.jsonBody
@@ -19,8 +20,23 @@ import java.util.UUID
 
 object EventEndpoints {
 
+  private val tagName = "Events"
+  private val tagDescription =
+    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
+       |- DIDComm connection notifications
+       |- Issuance protocol notifications
+       |- Presentation protocol notifications
+       |
+       |For more detailed information regarding event notifications, please refer to this [documentation](https://docs.atalaprism.io/tutorials/webhooks/webhook).
+       |""".stripMargin
+
+  val tag = Tag(tagName, Some(tagDescription))
+
   private val baseEndpoint = endpoint
-    .tag("Events")
+    .tag(tagName)
     .in("events")
     .securityIn(apiKeyHeader)
     .securityIn(jwtAuthHeader)
@@ -39,6 +55,11 @@ object EventEndpoints {
     .out(statusCode(StatusCode.Ok).description("Webhook notification has been created successfully"))
     .out(jsonBody[WebhookNotification])
     .summary("Create wallet webhook notifications")
+    .description(
+      """Create a new wallet webhook notification and subscribe to events.
+        |A dispatched webhook request may contain static custom headers for authentication or custom metadata.
+      """.stripMargin
+    )
 
   val listWebhookNotification: Endpoint[
     (ApiKeyCredentials, JwtCredentials),
@@ -52,6 +73,12 @@ object EventEndpoints {
     .out(statusCode(StatusCode.Ok).description("List wallet webhook notifications"))
     .out(jsonBody[WebhookNotificationPage])
     .summary("List wallet webhook notifications")
+    .description(
+      """List all registered webhook notifications.
+        |Each webhook notification contains a unique identifier, the URL to which the events are sent,
+        |and the custom headers to be included in the dispatched webhook request.
+      """.stripMargin
+    )
 
   val deleteWebhookNotification: Endpoint[
     (ApiKeyCredentials, JwtCredentials),

diff --git a/.../main/scala/org/hyperledger/identus/event/controller/http/CreateWebhookNotification.scala b/.../main/scala/org/hyperledger/identus/event/controller/http/CreateWebhookNotification.scala
@@ -1,9 +1,13 @@
 package org.hyperledger.identus.event.controller.http
 
+import org.hyperledger.identus.api.http.Annotation
 import sttp.tapir.Schema
+import sttp.tapir.Schema.annotations.{description, encodedExample}
 import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonEncoder, JsonDecoder}
 
 final case class CreateWebhookNotification(
+    @description(CreateWebhookNotification.annotations.url.description)
+    @encodedExample(CreateWebhookNotification.annotations.url.example)
     url: String,
     customHeaders: Option[Map[String, String]]
 )
@@ -12,4 +16,13 @@ object CreateWebhookNotification {
   given encoder: JsonEncoder[CreateWebhookNotification] = DeriveJsonEncoder.gen[CreateWebhookNotification]
   given decoder: JsonDecoder[CreateWebhookNotification] = DeriveJsonDecoder.gen[CreateWebhookNotification]
   given schema: Schema[CreateWebhookNotification] = Schema.derived
+
+  object annotations {
+    object url
+        extends Annotation[String](
+          description = "A URL of webhook for event notification",
+          example = "http://example.com"
+        )
+  }
+
 }
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,24 @@ 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 built-in 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.
+       |
+       |For more detailed information related to the agent IAM and its usage, please refer to this [documentation](https://docs.atalaprism.io/docs/atala-prism/prism-cloud-agent/authentication).
+       |""".stripMargin
+
+  val tag = Tag(tagName, Some(tagDescription))
+
   val createEntityEndpoint: Endpoint[
     (AdminApiKeyCredentials, JwtCredentials),
     (RequestContext, CreateEntityRequest),
@@ -48,7 +67,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 +103,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 +139,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,15 +164,12 @@ 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[
     (AdminApiKeyCredentials, JwtCredentials),
-    (
-        RequestContext,
-        PaginationInput
-    ),
+    (RequestContext, PaginationInput),
     ErrorResponse,
     EntityResponsePage,
     Any
@@ -171,7 +187,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 +214,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 +245,7 @@ object EntityEndpoints {
     .description(
       "Register the `apikey` for the entity."
     )
-    .tag("Identity and Access Management")
+    .tag(tagName)
 
   val deleteEntityApiKeyAuthenticationEndpoint: Endpoint[
     (AdminApiKeyCredentials, JwtCredentials),
@@ -260,5 +276,5 @@ object EntityEndpoints {
     .description(
       "Unregister the `apikey` for the entity."
     )
-    .tag("Identity and Access Management")
+    .tag(tagName)
 }