From bdc5d207a6d1567b9dca88f4d72300de091d1d24 Mon Sep 17 00:00:00 2001 From: Fabio Pinheiro Date: Fri, 14 Jun 2024 14:47:59 +0100 Subject: [PATCH] feat: improve OpenAPI's PresentProof to make more consistent (#1130) Signed-off-by: FabioPinheiro --- .../api/http/cloud-agent-openapi-spec.yaml | 22 +++++-- .../http/model/EntityResponsePage.scala | 4 +- .../controller/PresentProofEndpoints.scala | 7 ++- .../http/PresentationStatusPage.scala | 57 +++++++++++++++++-- 4 files changed, 75 insertions(+), 15 deletions(-) diff --git a/cloud-agent/service/api/http/cloud-agent-openapi-spec.yaml b/cloud-agent/service/api/http/cloud-agent-openapi-spec.yaml index 97e27cda12..3b9f36aac9 100644 --- a/cloud-agent/service/api/http/cloud-agent-openapi-spec.yaml +++ b/cloud-agent/service/api/http/cloud-agent-openapi-spec.yaml @@ -1925,7 +1925,8 @@ paths: tags: - Present Proof summary: Gets the list of proof presentation records. - description: list of presentation statuses + description: Get the list of proof presentation records and its status that + the Agent have at moment operationId: getAllPresentation parameters: - name: offset @@ -1946,6 +1947,7 @@ paths: format: int32 - name: thid in: query + description: Filter by the DID Comm message's 'thid' of presentProof required: false schema: type: string @@ -4631,7 +4633,11 @@ components: items: $ref: '#/components/schemas/PresentationStatus' description: A sequence of Presentation objects. - example: [] + example: + - PresentationStatus(938bfc23-f78d-4734-9bf3-6dccf300856f,04112f4d-e894-4bff-a706-85b3e7190a2c,Verifier,RequestSent,List(),List(),Some(e0d81be9-47ca-4e0b-b8a7-325e8c3abc2f),5) + - PresentationStatus(d22158b0-c650-48ea-be85-2920a845ef26,04112f4d-e894-4bff-a706-85b3e7190a2c,Prover,RequestReceived,List(),List(),None,5) + - PresentationStatus(fd3f5e54-fae9-4f72-9413-ec66aab83a57,6b42fd91-4c98-40ae-a371-a1fd1a39e05e,Prover,PresentationPending,List(),List(),None,5) + - PresentationStatus(e56dd3e0-79d0-45f4-ba6c-ff857211b07b,6b42fd91-4c98-40ae-a371-a1fd1a39e05e,Verifier,PresentationVerified,List(),List({"claimsToDisclose":{"emailAddress":{},"givenName":{}},"presentation":"{\"protected\":\"eyJhbGciOiJFZERTQSJ9\",\"payload\":\"eyJfc2QiOlsiMGl4d0tIV0dzbzFvZThFR0hQd2tGYW9EZE1TRFQ3SmgyNkZGSm1ZbGRnRSIsIjQ4VlFXZS1tcjBibHMyOWpicHFKeDNxX2dYY0k5N3dHcEpsZnRoNXQwMGciLCI0Wk9xanFNZVNUVHRKQTNJRExsc3ZXN0dTNzRIemNxY3N2NVFoZk1valE4IiwiUjhGRE0ydXB1V09mNmVJMVA5ckNPdG12c3puVWFFYXpncVNuN0JfeTE0MCIsIlU5MmpfUHlpcHN2TERNQTlDaVRWbnl3bUFzYTM4S2lDWm5TeVhyUE5mNG8iLCJldFB1Mmc5ajdRd01rZ3g5VnpEX1RnNTNUV3UydVpadk1KeHRnNEJ1WGJBIiwidGV3RG1LWklNcS10bUNrMkpqZU0wajNYbU1aUUFLN01heENVNlF4dm9OMCJdLCJfc2RfYWxnIjoic2hhLTI1NiIsImlzcyI6ImRpZDpwcmlzbToxMmEzOWI1YWEwZTcxODI3ZmMxYzYwMjg1ZDVlZWJjMTk0Yjg2NzFhYTJmY2QxZDM2NDBkMGYwMTBlMzliZmVlIiwiaWF0IjoxNzE3NDEwMzgzLCJleHAiOjE3MjAwMDIzODN9\",\"signature\":\"953FfSRU_0Y2q0ERrFPzbXJ_hkF0YQe5efwESaZwtXDCn8aanD3MUstp3lzqGZkhvcWRdtCCpIxzhy0zgKwLBg\",\"disclosures\":[\"WyI0SHF6MDZCeG5fRlJMb2hWX2lWNXp3IiwgImdpdmVuTmFtZSIsICJBbGljZSJd\",\"WyJLUnNYYU01c3NXZTl4UEhqQnNjT213IiwgImVtYWlsQWRkcmVzcyIsICJhbGljZUB3b25kZXJsYW5kLmNvbSJd\"],\"kb_jwt\":null}"}),Some(e0d81be9-47ca-4e0b-b8a7-325e8c3abc2f),5) self: type: string description: The reference to the presentation collection itself. @@ -4646,12 +4652,16 @@ components: example: 1 next: type: string - description: URL of the next page (if available) - example: '' + description: An optional string field containing the URL of the next page + of results. If the API response does not contain any more pages, this + field should be set to None. + example: /present-proof/presentations?offset=20&limit=10 previous: type: string - description: URL of the previous page (if available) - example: '' + description: An optional string field containing the URL of the previous + page of results. If the API response is the first page of results, this + field should be set to None. + example: /present-proof/presentations?offset=0&limit=10 Proof: required: - type diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/entity/http/model/EntityResponsePage.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/entity/http/model/EntityResponsePage.scala index cdf022c0b0..33d87e671b 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/entity/http/model/EntityResponsePage.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/entity/http/model/EntityResponsePage.scala @@ -10,7 +10,9 @@ import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder} case class EntityResponsePage( @description(annotations.contents.description) - @encodedExample(annotations.contents.example) + @encodedExample( // This is a hammer - to be improved in the future + JsonEncoder[Seq[EntityResponse]].encodeJson(annotations.contents.example) + ) contents: Seq[EntityResponse], @description(annotations.kind.description) @encodedExample(annotations.kind.example) diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/presentproof/controller/PresentProofEndpoints.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/presentproof/controller/PresentProofEndpoints.scala index c393029799..2534746a3d 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/presentproof/controller/PresentProofEndpoints.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/presentproof/controller/PresentProofEndpoints.scala @@ -17,6 +17,9 @@ import java.util.UUID object PresentProofEndpoints { private val paginationInput: EndpointInput[PaginationInput] = EndpointInput.derived[PaginationInput] + private val thidInput: EndpointInput[Option[String]] = + query[Option[String]]("thid") + .description("Filter by the DID Comm message's 'thid' of presentProof") val requestPresentation: Endpoint[ (ApiKeyCredentials, JwtCredentials), @@ -54,13 +57,13 @@ object PresentProofEndpoints { .tag("Present Proof") .name("getAllPresentation") .summary("Gets the list of proof presentation records.") - .description("list of presentation statuses") + .description("Get the list of proof presentation records and its status that the Agent have at moment") .securityIn(apiKeyHeader) .securityIn(jwtAuthHeader) .in("present-proof" / "presentations") .in(extractFromRequest[RequestContext](RequestContext.apply)) .in(paginationInput) - .in(query[Option[String]]("thid")) + .in(thidInput) .out(statusCode(StatusCode.Ok).description("The list of proof presentation records.")) .out(jsonBody[PresentationStatusPage]) .errorOut(basicFailuresAndForbidden) diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/presentproof/controller/http/PresentationStatusPage.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/presentproof/controller/http/PresentationStatusPage.scala index 7fa6593c6a..df72dc1107 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/presentproof/controller/http/PresentationStatusPage.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/presentproof/controller/http/PresentationStatusPage.scala @@ -8,7 +8,9 @@ import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder} final case class PresentationStatusPage( @description(annotations.contents.description) - @encodedExample(annotations.contents.example) + @encodedExample( // This is a hammer - to be improved in the future + JsonEncoder[Seq[PresentationStatus]].encodeJson(annotations.contents.example) + ) contents: Seq[PresentationStatus], @description(annotations.self.description) @encodedExample(annotations.self.example) @@ -46,18 +48,61 @@ object PresentationStatusPage { ) object next extends Annotation[String]( - description = "URL of the next page (if available)", - example = "" + description = + "An optional string field containing the URL of the next page of results. If the API response does not contain any more pages, this field should be set to None.", + example = "/present-proof/presentations?offset=20&limit=10" ) object previous extends Annotation[String]( - description = "URL of the previous page (if available)", - example = "" + description = + "An optional string field containing the URL of the previous page of results. If the API response is the first page of results, this field should be set to None.", + example = "/present-proof/presentations?offset=0&limit=10" ) object contents extends Annotation[Seq[PresentationStatus]]( description = "A sequence of Presentation objects.", - example = Seq.empty + example = Seq( + PresentationStatus( + presentationId = "938bfc23-f78d-4734-9bf3-6dccf300856f", + thid = "04112f4d-e894-4bff-a706-85b3e7190a2c", + role = "Verifier", + status = "RequestSent", + proofs = Seq.empty, + data = Seq.empty, + connectionId = Some("e0d81be9-47ca-4e0b-b8a7-325e8c3abc2f"), + metaRetries = 5 + ), + PresentationStatus( + presentationId = "d22158b0-c650-48ea-be85-2920a845ef26", + thid = "04112f4d-e894-4bff-a706-85b3e7190a2c", + role = "Prover", + status = "RequestReceived", + proofs = Seq.empty, + data = Seq.empty, + metaRetries = 5 + ), + PresentationStatus( + presentationId = "fd3f5e54-fae9-4f72-9413-ec66aab83a57", + thid = "6b42fd91-4c98-40ae-a371-a1fd1a39e05e", + role = "Prover", + status = "PresentationPending", + proofs = Seq.empty, + data = Seq.empty, + metaRetries = 5 + ), + PresentationStatus( + presentationId = "e56dd3e0-79d0-45f4-ba6c-ff857211b07b", + thid = "6b42fd91-4c98-40ae-a371-a1fd1a39e05e", + role = "Verifier", + status = "PresentationVerified", + proofs = Seq.empty, + data = Seq( + "{\"claimsToDisclose\":{\"emailAddress\":{},\"givenName\":{}},\"presentation\":\"{\\\"protected\\\":\\\"eyJhbGciOiJFZERTQSJ9\\\",\\\"payload\\\":\\\"eyJfc2QiOlsiMGl4d0tIV0dzbzFvZThFR0hQd2tGYW9EZE1TRFQ3SmgyNkZGSm1ZbGRnRSIsIjQ4VlFXZS1tcjBibHMyOWpicHFKeDNxX2dYY0k5N3dHcEpsZnRoNXQwMGciLCI0Wk9xanFNZVNUVHRKQTNJRExsc3ZXN0dTNzRIemNxY3N2NVFoZk1valE4IiwiUjhGRE0ydXB1V09mNmVJMVA5ckNPdG12c3puVWFFYXpncVNuN0JfeTE0MCIsIlU5MmpfUHlpcHN2TERNQTlDaVRWbnl3bUFzYTM4S2lDWm5TeVhyUE5mNG8iLCJldFB1Mmc5ajdRd01rZ3g5VnpEX1RnNTNUV3UydVpadk1KeHRnNEJ1WGJBIiwidGV3RG1LWklNcS10bUNrMkpqZU0wajNYbU1aUUFLN01heENVNlF4dm9OMCJdLCJfc2RfYWxnIjoic2hhLTI1NiIsImlzcyI6ImRpZDpwcmlzbToxMmEzOWI1YWEwZTcxODI3ZmMxYzYwMjg1ZDVlZWJjMTk0Yjg2NzFhYTJmY2QxZDM2NDBkMGYwMTBlMzliZmVlIiwiaWF0IjoxNzE3NDEwMzgzLCJleHAiOjE3MjAwMDIzODN9\\\",\\\"signature\\\":\\\"953FfSRU_0Y2q0ERrFPzbXJ_hkF0YQe5efwESaZwtXDCn8aanD3MUstp3lzqGZkhvcWRdtCCpIxzhy0zgKwLBg\\\",\\\"disclosures\\\":[\\\"WyI0SHF6MDZCeG5fRlJMb2hWX2lWNXp3IiwgImdpdmVuTmFtZSIsICJBbGljZSJd\\\",\\\"WyJLUnNYYU01c3NXZTl4UEhqQnNjT213IiwgImVtYWlsQWRkcmVzcyIsICJhbGljZUB3b25kZXJsYW5kLmNvbSJd\\\"],\\\"kb_jwt\\\":null}\"}" + ), + connectionId = Some("e0d81be9-47ca-4e0b-b8a7-325e8c3abc2f"), + metaRetries = 5 + ), + ) ) }