From db4778f5324519fb8c93070361a698b006b071aa Mon Sep 17 00:00:00 2001 From: Gerard Snaauw Date: Mon, 5 Jul 2021 12:53:30 +0200 Subject: [PATCH] update vdr & vcr docs --- docs/_static/vcr/v1.yaml | 181 ++++++++++++++------------------------- docs/_static/vdr/v1.yaml | 180 ++++++++++++-------------------------- 2 files changed, 118 insertions(+), 243 deletions(-) diff --git a/docs/_static/vcr/v1.yaml b/docs/_static/vcr/v1.yaml index 097dd52f0a..632d95813c 100644 --- a/docs/_static/vcr/v1.yaml +++ b/docs/_static/vcr/v1.yaml @@ -9,6 +9,12 @@ paths: /internal/vcr/v1/vc: post: summary: Creates a new Verifiable Credential + description: | + Creates a new Verifiable Credential. + + error returns: + * 400 - One or more of the given parameters are invalid + * 500 - An error occurred while processing the request operationId: "create" tags: - credential @@ -25,18 +31,8 @@ paths: application/vc+json: schema: $ref: '#/components/schemas/VerifiableCredential' - "400": - description: One or more of the given parameters are invalid - content: - text/plain: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' /internal/vcr/v1/vc/{id}: parameters: - name: id @@ -52,6 +48,10 @@ paths: description: > The resolutionResult contains the credential regardless of the validity. The resolutionResult.currentStatus must be checked to see if the credential is valid. + + error returns: + * 404 - Corresponding credential could not be found + * 500 - An error occurred while processing the request operationId: "resolve" tags: - credential @@ -62,20 +62,18 @@ paths: application/vc+json: schema: $ref: '#/components/schemas/ResolutionResult' - "404": - description: Corresponding credential could not be found. - content: - text/plain: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' delete: summary: "Revoke a credential" + description: | + Revoke a credential. + + error returns: + * 400 - Credential can't be revoked. Most likely due to a missing private key. + * 404 - Credential is not found + * 409 - Credential has already been revoked + * 500 - An error occurred while processing the request operationId: "revoke" tags: - credential @@ -86,33 +84,18 @@ paths: application/vc+json;type=revocation: schema: $ref: '#/components/schemas/Revocation' - "400": - description: Credential can't be revoked. Most likely due to a missing private key. - content: - text/plain: - schema: - type: string - "404": - description: Credential is not found. - content: - text/plain: - schema: - type: string - "409": - description: Credential has already been revoked. - content: - text/plain: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' /internal/vcr/v1/{concept}: post: summary: Search for a concept. A concept is backed by 1 or more VCs + description: | + Search for a concept. A concept is backed by 1 or more VCs. + + error returns: + * 400 - Invalid paramters + * 404 - Concept not found + * 500 - An error occurred while processing the request operationId: "search" tags: - credential @@ -140,28 +123,17 @@ paths: items: description: the returned JSON depends on the requested concept. type: object - "400": - description: invalid params. - content: - text/plain: - schema: - type: string - "404": - description: concept not found. - content: - text/plain: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' /internal/vcr/v1/trust: post: summary: Mark all the VCs of given type and issuer as 'trusted'. - description: The added trust is persisted and may be removed with a delete operation. + description: | + The added trust is persisted and may be removed with a delete operation. + + error returns: + * 400 - Invalid paramters + * 500 - An error occurred while processing the request operationId: "trustIssuer" tags: - credential @@ -175,21 +147,16 @@ paths: responses: "204": description: The change was accepted. - "400": - description: invalid params. - content: - text/plain: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' delete: summary: Remove trust in an issuer/credentialType combination - description: The removed trust is persisted. + description: | + The removed trust is persisted. + + error returns: + * 400 - Invalid paramters + * 500 - An error occurred while processing the request operationId: "untrustIssuer" tags: - credential @@ -203,21 +170,17 @@ paths: responses: "204": description: The change was accepted. - "400": - description: invalid params. - content: - text/plain: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' /internal/vcr/v1/{credentialType}/trusted: get: summary: "List all trusted issuers for a given credential type" + description: | + List all trusted issuers for a given credential type. + + error returns: + * 400 - Malformed credential type + * 404 - Unkown credential type operationId: "listTrusted" tags: - credential @@ -239,21 +202,17 @@ paths: type: array items: $ref: '#/components/schemas/DID' - "400": - description: malformed credential type. - content: - text/plain: - schema: - type: string - "404": - description: unknown credential type. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' /internal/vcr/v1/{credentialType}/untrusted: get: summary: "List all untrusted issuers for a given credential type" + description: | + List all untrusted issuers for a given credential type. + + error returns: + * 400 - Malformed credential type + * 404 - Unkown credential type operationId: "listUntrusted" tags: - credential @@ -275,18 +234,8 @@ paths: type: array items: $ref: '#/components/schemas/DID' - "400": - description: malformed credential type. - content: - text/plain: - schema: - type: string - "404": - description: unknown credential type. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' components: schemas: CredentialSubject: diff --git a/docs/_static/vdr/v1.yaml b/docs/_static/vdr/v1.yaml index 8d25ef4796..201275fff1 100644 --- a/docs/_static/vdr/v1.yaml +++ b/docs/_static/vdr/v1.yaml @@ -13,6 +13,10 @@ paths: The DID Document will be created according to the given request. If a combination of options is not allowed, a 400 is returned. The default values for selfControl, assertionMethod and capabilityInvocation are true. The default for controllers is an empty list. All other options default to false. Only a single keypair will be generated. All enabled methods will reuse the same key pair. A seperate keypair will be generated to generate the DID if SelfControl is false. + + error returns: + * 400 - Invalid (combination of) options + * 500 - An error occurred while processing the request operationId: "createDID" requestBody: required: true @@ -29,18 +33,8 @@ paths: application/json+did-document: schema: $ref: '#/components/schemas/DIDDocument' - "400": - description: "Conflicting options given." - content: - application/json: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' /internal/vdr/v1/did/{did}: parameters: - name: did @@ -53,6 +47,13 @@ paths: type: string get: summary: "Resolves a Nuts DID document" + description: | + Resolves a Nuts DID document + + error returns: + * 400 - Returned in case of malformed DID + * 404 - Corresponding DID document could not be found + * 500 - An error occurred while processing the request operationId: "getDID" tags: - DID @@ -63,26 +64,19 @@ paths: application/json: schema: $ref: '#/components/schemas/DIDResolutionResult' - "400": - description: Returned in case of malformed DID. - content: - text/plain: - schema: - type: string - "404": - description: Corresponding DID document could not be found. - content: - text/plain: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' put: summary: Updates a Nuts DID document. + description: | + Updates a Nuts DID document. + + error returns: + * 400 - DID document could not be updated because the DID param was malformed or the DID document is invalid + * 403 - DID document could not be updated because the DID is not managed by this node + * 404 - Corresponding DID document could not be found + * 409 - DID document could not be updated because the the document was already deactivated + * 500 - An error occurred while processing the request operationId: "updateDID" tags: - DID @@ -99,74 +93,27 @@ paths: application/json+did-document: schema: $ref: '#/components/schemas/DIDDocument' - "400": - description: DID document couldn't be updated because the DID param was malformed or the DID document is invalid. - content: - text/plain: - schema: - type: string - "409": - description: DID document couldn't be updated because the the document was already deactivated. - content: - text/plain: - schema: - type: string - "403": - description: DID document couldn't be updated because the DID is not managed by this node. - content: - text/plain: - schema: - type: string - "404": - description: Corresponding DID document could not be found. - content: - text/plain: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' delete: summary: Deactivates a Nuts DID document according to the specification. + description: | + Updates a Nuts DID document. + + error returns: + * 400 - DID document could not be deleted because the DID param was malformed + * 403 - DID document could not be deleted because the DID is not managed by this node + * 404 - Corresponding DID document could not be found + * 409 - DID document could not be deactivated because the the document was already deactivated + * 500 - An error occurred while processing the request operationId: "deactivateDID" tags: - DID responses: "200": description: DID document has been deactivated. - "400": - description: DID document couldn't be deleted because the DID param was malformed. - content: - text/plain: - schema: - type: string - "403": - description: DID document couldn't be deleted because the DID is not managed by this node. - content: - text/plain: - schema: - type: string - "404": - description: Corresponding DID document could not be found. - content: - text/plain: - schema: - type: string - "409": - description: DID document couldn't be deactivated because the the document was already deactivated. - content: - text/plain: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' /internal/vdr/v1/did/{did}/verificationmethod: parameters: - name: did @@ -179,7 +126,13 @@ paths: type: string post: summary: Creates and adds a new verificationMethod to the DID document. - description: It create a new private public keypair. The public key is wrapped in verificationMethod. This method is added to the DID Document. + description: | + It create a new private public keypair. The public key is wrapped in verificationMethod. This method is added to the DID Document. + + error returns: + * 403 - Verification method could not be added because the DID is not managed by this node + * 404 - Corresponding DID document could not be found + * 500 - An error occurred while processing the request operationId: addNewVerificationMethod tags: - DID @@ -190,24 +143,8 @@ paths: application/json+did-document: schema: $ref: '#/components/schemas/VerificationMethod' - "403": - description: Verification method could not be added because the DID is not managed by this node. - content: - text/plain: - schema: - type: string - "404": - description: Corresponding DID document could not be found. - content: - text/plain: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' /internal/vdr/v1/did/{did}/verificationmethod/{kid}: parameters: - name: did @@ -232,28 +169,17 @@ paths: Removes the verification method from the DID Document. Revokes the public key with the corresponding key-id. Note: Other verification methods with different key-ids with the same private key will still be valid. + + error returns: + * 403 - Verification method could not be deleted because the DID is not managed by this node + * 404 - Corresponding DID document or verification method could not be found + * 500 - An error occurred while processing the request operationId: deleteVerificationMethod responses: "204": description: Verification Method was successfully deleted - "403": - description: Verification method could not be deleted because the DID is not managed by this node. - content: - text/plain: - schema: - type: string - "404": - description: Corresponding DID document or verification method could not be found. - content: - text/plain: - schema: - type: string - "500": - description: An error occurred while processing the request. - content: - text/plain: - schema: - type: string + default: + $ref: '../common/error_response.yaml' components: schemas: DIDDocument: