From cf156d99690138e62c30d0a2be09f0e4e72680f0 Mon Sep 17 00:00:00 2001 From: patlo-iog Date: Fri, 3 May 2024 18:35:33 +0700 Subject: [PATCH] docs: improve OAS docs for Event and IAM section (#1007) Signed-off-by: Pat Losoponkul Co-authored-by: Yurii Shynbuiev - IOHK --- .../identus/agent/server/http/DocModels.scala | 8 +++- .../event/controller/EventEndpoints.scala | 29 +++++++++++++- .../http/CreateWebhookNotification.scala | 13 ++++++ .../iam/entity/http/EntityEndpoints.scala | 40 +++++++++++++------ 4 files changed, 75 insertions(+), 15 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..fa72fabd34 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,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/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..c2d961bde9 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 + |- 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/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" + ) + } + } diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/entity/http/EntityEndpoints.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/entity/http/EntityEndpoints.scala index d8e5014d3d..02c0df8fb8 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/entity/http/EntityEndpoints.scala +++ b/cloud-agent/service/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) }