docs: make event oas doc beautiful

Signed-off-by: Pat Losoponkul <pat.losoponkul@iohk.io>
hyperledger · May 3, 2024 · bfb6026 · bfb6026
1 parent 32ec1f6
commit bfb6026
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 3 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,9 @@ 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.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 +13,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 +116,8 @@ object DocModels {
           DIDEndpoints.tag,
           DIDRegistrarEndpoints.tag,
           WalletManagementEndpoints.tag,
-          SystemEndpoints.tag
+          SystemEndpoints.tag,
+          EventEndpoints.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
+       |- Issuance protocol state change notifications
+       |- DIDComm connection 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"
+        )
+  }
+
 }