From d99bcd2cb3466c4857d095c6db141c43d55850dc Mon Sep 17 00:00:00 2001 From: Daniel Mader Date: Sun, 29 Sep 2024 22:53:44 +0200 Subject: [PATCH] docs: add examples --- agent_api_rest/openapi.yaml | 78 +++++++++++++++---- agent_api_rest/src/issuance/credentials.rs | 28 +++++-- agent_api_rest/src/issuance/offers/mod.rs | 8 +- agent_api_rest/src/lib.rs | 8 +- .../verification/authorization_requests.rs | 3 + .../verification/relying_party/redirect.rs | 2 +- .../src/verification/relying_party/request.rs | 2 +- 7 files changed, 97 insertions(+), 32 deletions(-) diff --git a/agent_api_rest/openapi.yaml b/agent_api_rest/openapi.yaml index 28c00b6..e779a14 100644 --- a/agent_api_rest/openapi.yaml +++ b/agent_api_rest/openapi.yaml @@ -6,7 +6,7 @@ info: name: '' version: '' servers: -- url: https://arty-aragorn.agent-dev.impierce.com +- url: https://playground.agent-dev.impierce.com description: UniCore development server hosted by Impierce Technologies paths: /.well-known/oauth-authorization-server: @@ -114,7 +114,9 @@ paths: schema: $ref: '#/components/schemas/GenericAuthorizationResponse' required: true - responses: {} + responses: + '200': + description: '' /request/{id}: get: tags: @@ -133,7 +135,9 @@ paths: required: true schema: type: string - responses: {} + responses: + '200': + description: '' /v0/authorization_requests: post: tags: @@ -160,6 +164,7 @@ paths: parameters: - name: id in: path + description: The ID of the Authorization Request to retrieve. required: true schema: type: string @@ -175,19 +180,56 @@ paths: /v0/credentials: post: tags: - - Credentials + - Issuance summary: Create a new credential - description: Create a new credential for the given payload. + description: Create a new credential for a given subject. operationId: credentials requestBody: content: application/json: schema: $ref: '#/components/schemas/CredentialsEndpointRequest' + examples: + openbadges: + summary: Open Badges 3.0 + description: s0me descr1pti0n + externalValue: res/open-badge-request.json + w3c-vc: + summary: W3C v1.1 + description: s0me descr1pti0n + value: + offerId: 123 + credentialConfigurationId: w3c_vc_credential + credential: + credentialSubject: + first_name: Ferris + last_name: Rustacean required: true responses: - '200': + '201': description: Successfully created a new credential. + headers: + Location: + schema: + type: string + description: URL of the created resource + content: + application/json: + schema: + $ref: '#/components/schemas/CredentialView' + examples: + openbadges-3-0: + summary: Open Badges 3.0 + description: An badge following the Open Badges Specification 3.0 + value: + foo: bar + w3c-vc-1-1: + summary: W3C VC Data Model v1.1 + description: A credential following the W3C Verifiable Credentials Data Model v1.1 + value: + offerId: '0001' + '400': + description: Invalid payload. /v0/credentials/{id}: get: tags: @@ -198,12 +240,10 @@ paths: parameters: - name: id in: path - description: Unique identitfier of the Credential + description: Unique identifier of the Credential required: true schema: - type: integer - format: int64 - minimum: 0 + type: string responses: '200': description: Credential found @@ -268,9 +308,9 @@ paths: /v0/offers: post: tags: - - Offers - summary: Create a new offer - description: Create a new credential offer for the given ID. + - Issuance + summary: Create a new credential offer + description: Create a new offer for one or more credentials. operationId: offers requestBody: content: @@ -280,7 +320,12 @@ paths: required: true responses: '200': - description: Successfully created a new credential offer. + description: Successfully created a new credential offer. Response value is standard-compliant and can be used by identity wallet. + content: + application/x-www-form-urlencoded: + schema: + type: string + example: openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fcredential-issuer.example.com%2F%22%2C%22credentials%22%3A%5B%7B%22format%22%3A%22ldp_vc%22%2C%22credential_definition%22%3A%7B%22%40context%22%3A%5B%22https%3A%2F%2Fwww.w3.org%2F2018%2Fcredentials%2Fv1%22%2C%22https%3A%2F%2Fwww.w3.org%2F2018%2Fcredentials%2Fexamples%2Fv1%22%5D%2C%22type%22%3A%5B%22VerifiableCredential%22%2C%22UniversityDegreeCredential%22%5D%7D%7D%5D%7D components: schemas: CredentialsEndpointRequest: @@ -306,4 +351,7 @@ tags: description: Issue credentials to holders that will store them in their wallets. externalDocs: url: https://docs.impierce.com - description: Official Documentation + description: Issuance API Documentation +externalDocs: + url: https://docs.impierce.com + description: Official Documentation diff --git a/agent_api_rest/src/issuance/credentials.rs b/agent_api_rest/src/issuance/credentials.rs index 416c37b..f66e234 100644 --- a/agent_api_rest/src/issuance/credentials.rs +++ b/agent_api_rest/src/issuance/credentials.rs @@ -25,11 +25,11 @@ use utoipa::ToSchema; get, path = "/credentials/{id}", tag = "Credentials", + params( + ("id" = String, Path, description = "Unique identifier of the Credential"), + ), responses( (status = 200, description = "Credential found", body = [CredentialView]) - ), - params( - ("id" = u64, Path, description = "Unique identitfier of the Credential"), ) )] #[axum_macros::debug_handler] @@ -57,15 +57,27 @@ pub struct CredentialsEndpointRequest { /// Create a new credential /// -/// Create a new credential for the given payload. +/// Create a new credential for a given subject. #[utoipa::path( post, path = "/credentials", - request_body = CredentialsEndpointRequest, - tag = "Credentials", + request_body(content = CredentialsEndpointRequest, + examples( + ("w3c-vc" = (summary = "W3C v1.1", description = "s0me descr1pti0n", value = json!({"offerId": 123, "credentialConfigurationId": "w3c_vc_credential", "credential": {"credentialSubject": {"first_name": "Ferris", "last_name": "Rustacean"}}}))), + ("openbadges" = (summary = "Open Badges 3.0", description = "s0me descr1pti0n", external_value = "res/open-badge-request.json")) + ) + ), + tag = "Issuance", responses( - (status = 200, description = "Successfully created a new credential.") - ) + (status = 201, description = "Successfully created a new credential.", body = CredentialView, + headers(("Location" = String, description = "URL of the created resource")), + examples( + ("w3c-vc-1-1" = (summary = "W3C VC Data Model v1.1", description = "A credential following the W3C Verifiable Credentials Data Model v1.1", value = json!({"offerId": "0001"}))), + ("openbadges-3-0" = (summary = "Open Badges 3.0", description = "An badge following the Open Badges Specification 3.0", value = json!({"foo": "bar"}))) + ) + ), + (status = 400, description = "Invalid payload.") + ), )] #[axum_macros::debug_handler] pub(crate) async fn credentials( diff --git a/agent_api_rest/src/issuance/offers/mod.rs b/agent_api_rest/src/issuance/offers/mod.rs index c8140f3..2d0abb8 100644 --- a/agent_api_rest/src/issuance/offers/mod.rs +++ b/agent_api_rest/src/issuance/offers/mod.rs @@ -23,16 +23,16 @@ pub struct OffersEndpointRequest { pub offer_id: String, } -/// Create a new offer +/// Create a new credential offer /// -/// Create a new credential offer for the given ID. +/// Create a new offer for one or more credentials. #[utoipa::path( post, path = "/offers", request_body = OffersEndpointRequest, - tag = "Offers", + tag = "Issuance", responses( - (status = 200, description = "Successfully created a new credential offer.") + (status = 200, description = "Successfully created a new credential offer. Response value is standard-compliant and can be used by identity wallet.", body = String, content_type = "application/x-www-form-urlencoded", example = json!("openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fcredential-issuer.example.com%2F%22%2C%22credentials%22%3A%5B%7B%22format%22%3A%22ldp_vc%22%2C%22credential_definition%22%3A%7B%22%40context%22%3A%5B%22https%3A%2F%2Fwww.w3.org%2F2018%2Fcredentials%2Fv1%22%2C%22https%3A%2F%2Fwww.w3.org%2F2018%2Fcredentials%2Fexamples%2Fv1%22%5D%2C%22type%22%3A%5B%22VerifiableCredential%22%2C%22UniversityDegreeCredential%22%5D%7D%7D%5D%7D")) ) )] #[axum_macros::debug_handler] diff --git a/agent_api_rest/src/lib.rs b/agent_api_rest/src/lib.rs index abcbae9..bce7b0b 100644 --- a/agent_api_rest/src/lib.rs +++ b/agent_api_rest/src/lib.rs @@ -117,8 +117,9 @@ fn get_base_path() -> Result { tags( (name = "(public)", description = "A collection of endpoints that should be publicly accessible without authentication. They are used to resolve metadata or allow communication with wallets."), (name = "(.well-known)", description = "Well-known endpoints provide metadata about the server."), - (name = "Issuance", description = "Issue credentials to holders that will store them in their wallets.", external_docs(description="Official Documentation", url="https://docs.impierce.com")), - ) + (name = "Issuance", description = "Issue credentials to holders that will store them in their wallets.", external_docs(description="Issuance API Documentation", url="https://docs.impierce.com")), + ), + external_docs(description="Official Documentation", url="https://docs.impierce.com"), )] pub struct ApiDoc; @@ -127,8 +128,9 @@ pub fn patch_generated_openapi(mut openapi: utoipa::openapi::OpenApi) -> utoipa: openapi.info.description = Some("Full HTTP API reference for the UniCore SSI Agent".to_string()); // openapi.info.version = "1.0.0-alpha.1".into(); // can UniCore even be aware of its current version or does it need to be removed from the openapi.yaml? openapi.info.version = "".into(); + // TODO: deploy openapi.servers = vec![ServerBuilder::new() - .url("https://arty-aragorn.agent-dev.impierce.com") + .url("https://playground.agent-dev.impierce.com") .description(Some("UniCore development server hosted by Impierce Technologies")) .build()] .into(); diff --git a/agent_api_rest/src/verification/authorization_requests.rs b/agent_api_rest/src/verification/authorization_requests.rs index 36c1cb4..fa0804a 100644 --- a/agent_api_rest/src/verification/authorization_requests.rs +++ b/agent_api_rest/src/verification/authorization_requests.rs @@ -27,6 +27,9 @@ use utoipa::ToSchema; get, path = "/authorization_requests/{id}", tag = "Verification", + params( + ("id" = String, Path, description = "The ID of the Authorization Request to retrieve.") + ), responses( (status = 200, description = "Successfully returns an existing Authorization Request.", body = [GenericAuthorizationRequest]) ) diff --git a/agent_api_rest/src/verification/relying_party/redirect.rs b/agent_api_rest/src/verification/relying_party/redirect.rs index 8e6258d..a61de50 100644 --- a/agent_api_rest/src/verification/relying_party/redirect.rs +++ b/agent_api_rest/src/verification/relying_party/redirect.rs @@ -18,7 +18,7 @@ use axum::{ path = "/redirect", tags = ["(public)"], responses( - // (status = 200, description = ""), + (status = 200, description = ""), ) )] #[axum_macros::debug_handler] diff --git a/agent_api_rest/src/verification/relying_party/request.rs b/agent_api_rest/src/verification/relying_party/request.rs index 8c89279..a9aa319 100644 --- a/agent_api_rest/src/verification/relying_party/request.rs +++ b/agent_api_rest/src/verification/relying_party/request.rs @@ -19,7 +19,7 @@ use hyper::header; path = "/request/{id}", tags = ["(public)"], responses( - // (status = 200, description = ""), + (status = 200, description = ""), ) )] #[axum_macros::debug_handler]