From eeb8a4d615466ed63a697a8184a01d0c4464ab06 Mon Sep 17 00:00:00 2001 From: Pat Losoponkul Date: Fri, 3 May 2024 14:03:10 +0700 Subject: [PATCH] docs: make event oas doc beautiful --- .../identus/agent/server/http/DocModels.scala | 6 ++-- .../event/controller/EventEndpoints.scala | 29 ++++++++++++++++++- .../http/CreateWebhookNotification.scala | 13 +++++++++ 3 files changed, 45 insertions(+), 3 deletions(-) diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/agent/server/http/DocModels.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/agent/server/http/DocModels.scala index f80c886577..2c1ef2e852 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/agent/server/http/DocModels.scala +++ b/cloud-agent/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/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/event/controller/EventEndpoints.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/event/controller/EventEndpoints.scala index 0320224faf..a7a0168907 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/event/controller/EventEndpoints.scala +++ b/cloud-agent/service/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/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/event/controller/http/CreateWebhookNotification.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/event/controller/http/CreateWebhookNotification.scala index e6e413bfc4..4fbef5f1ae 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/event/controller/http/CreateWebhookNotification.scala +++ b/cloud-agent/service/server/src/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" + ) + } + }