From 44aaff929c220228a40231aad84c0ace90c7535b Mon Sep 17 00:00:00 2001 From: Mal <=> Date: Fri, 21 Aug 2020 23:47:13 +0200 Subject: [PATCH] OpenAPI documentation added --- api/v1/openapi.yaml | 475 ++++++++++++++++++++++++++++++++++++++++++++ docs/api/v1.yaml | 0 2 files changed, 475 insertions(+) create mode 100644 api/v1/openapi.yaml delete mode 100644 docs/api/v1.yaml diff --git a/api/v1/openapi.yaml b/api/v1/openapi.yaml new file mode 100644 index 0000000..d24ef3c --- /dev/null +++ b/api/v1/openapi.yaml @@ -0,0 +1,475 @@ +openapi: 3.0.0 + +info: + title: Ringfinger API + version: 1.0.0 + description: The restfull API of the jabber fingerprint keyring. + +servers: + - url: https://sabolli.de/ringfinger + description: Test server + +tags: + - name: User + description: A user that can login, store fingerprints and share them with other users. + - name: Fingerprint + description: The jabber fingerprint owned by a user. + - name: Sharing + description: The sharing of all fingerprints of a user with another user. + +paths: + '/api/v1/user/{userId}': + get: + tags: + - User + summary: Returns the user attributes + parameters: + - $ref: '#/components/parameters/UserId' + responses: + 200: + description: Returns the user data for the given id. + content: + application/json: + schema: + type: object + properties: + success: + $ref: '#/components/schemas/Success' + result: + type: object + description: Contains the user data. + properties: + userId: + $ref: '#/components/schemas/UserId' + usernamme: + $ref: '#/components/schemas/Username' + jabberAddress: + $ref: '#/components/schemas/JabberAddress' + fingerprintIds: + type: array + items: + type: integer + description: A list of all fingerprint ids of the user. + example: [25, 42, 88] + default: [] + default: + $ref: '#/components/responses/Error' + put: + tags: + - User + summary: Changes user attributes + parameters: + - $ref: '#/components/parameters/UserId' + requestBody: + required: true + description: Contains the json with the user attributes that have to be changed. + content: + application/json: + schema: + properties: + username: + $ref: '#/components/schemas/Username' + password: + $ref: '#/components/schemas/Password' + email: + $ref: '#/components/schemas/EmailAddress' + jabberAddress: + $ref: '#/components/schemas/JabberAddress' + responses: + 200: + $ref: '#/components/responses/Success' + default: + $ref: '#/components/responses/Error' + delete: + tags: + - User + summary: Deletes a user + parameters: + - $ref: '#/components/parameters/UserId' + responses: + 200: + $ref: '#/components/responses/Success' + default: + $ref: '#/components/responses/Error' + + '/api/v1/user': + post: + tags: + - User + summary: Creates a new user + requestBody: + required: true + description: 'The attributes for the user to be created.' + content: + application/json: + schema: + properties: + username: + $ref: '#/components/schemas/Username' + password: + $ref: '#/components/schemas/Password' + email: + $ref: '#/components/schemas/EmailAddress' + jabberAddress: + $ref: '#/components/schemas/JabberAddress' + allOf: + - required: + - username + - password + - email + - jabberAddress + responses: + 200: + $ref: '#/components/responses/Success' + default: + $ref: '#/components/responses/Error' + + '/api/v1/user/session': + post: + tags: + - User + summary: Creates a user session (login) + requestBody: + required: true + content: + application/json: + schema: + properties: + username: + $ref: '#/components/schemas/Username' + password: + $ref: '#/components/schemas/Password' + allOf: + - required: + - username + - password + responses: + 200: + description: Returns the success state and the user id for the created session. + content: + application/json: + schema: + properties: + success: + $ref: '#/components/schemas/Success' + userId: + $ref: '#/components/schemas/UserId' + default: + $ref: '#/components/responses/Error' + delete: + tags: + - User + summary: Deletes a user session (logout) + responses: + 200: + $ref: '#/components/responses/Success' + default: + $ref: '#/components/responses/Error' + + '/api/v1/fingerprint/{fingerprintId}/qr': + get: + tags: + - Fingerprint + summary: Returns the fingerprint's QR code + parameters: + - $ref: '#/components/parameters/FingerprintId' + responses: + 200: + description: The QR code as SVG image + content: + application/svg+xml: + schema: + type: string + description: The xml of the SVG image. + default: + $ref: '#/components/responses/Error' + + '/api/v1/fingerprint/{fingerprintId}': + get: + tags: + - Fingerprint + summary: Returns the attributes of the fingerprint + parameters: + - $ref: '#/components/parameters/FingerprintId' + responses: + 200: + description: Returns the fingerprint for the given fingerprint id. + content: + application/json: + schema: + type: object + properties: + fingerprintId: + $ref: '#/components/schemas/FingerprintId' + fingerprint: + $ref: '#/components/schemas/Fingerprint' + userId: + type: integer + description: The id of the user that owns this fingerprint. + example: 25 + default: + $ref: '#/components/responses/Error' + put: + tags: + - Fingerprint + summary: Changes the fingerprint + parameters: + - $ref: '#/components/parameters/FingerprintId' + requestBody: + content: + application/json: + schema: + properties: + fingerprint: + $ref: '#/components/schemas/Fingerprint' + required: + - fingerprint + responses: + 200: + description: Returns the success state. + content: + application/json: + schema: + properties: + success: + type: boolean + description: 'Returns the success state of the fingerprint change.' + example: true + message: + type: string + description: 'Returns if no changes have been found inside the request body.' + example: 'Fingerprint did not differ from the stored. Nothing changed.' + required: + - success + default: + $ref: '#/components/responses/Error' + + delete: + tags: + - Fingerprint + summary: Removes the fingerprint + parameters: + - $ref: '#/components/parameters/FingerprintId' + responses: + 200: + $ref: '#/components/responses/Success' + default: + $ref: '#/components/responses/Error' + + '/api/v1/fingerprint': + post: + tags: + - Fingerprint + summary: Creates a new fingerprint + requestBody: + content: + application/json: + schema: + description: The parameters for the new fingerprint to be created. + properties: + fingerprint: + $ref: '#/components/schemas/Fingerprint' + userId: + $ref: '#/components/schemas/UserId' + required: + - fingerprint + - userId + + responses: + 200: + description: Returns the confirmation and the id for the newly created fingerprint. + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + description: Returns the success status. + example: true + fingerprintId: + type: integer + description: The id for the newly created fingerprint. + example: 42 + default: + $ref: '#/components/responses/Error' + + '/api/v1/sharing/{sharingId}': + get: + tags: + - Sharing + summary: Returns the sharing attributes + parameters: + - $ref: '#/components/parameters/SharingId' + responses: + 200: + description: The JSON result for the sharing. + content: + application/json: + schema: + properties: + success: + $ref: '#/components/schemas/Success' + result: + type: object + properties: + sharingId: + $ref: '#/components/schemas/SharingId' + userId: + type: integer + description: The id of the user that shares his fingerprints. + example: 42 + userSharedId: + $ref: '#/components/schemas/SharingUserId' + default: + $ref: '#/components/responses/Error' + delete: + tags: + - Sharing + summary: Removes the specified sharing + parameters: + - $ref: '#/components/parameters/SharingId' + responses: + 200: + $ref: '#/components/responses/Success' + default: + $ref: '#/components/responses/Error' + + '/api/v1/sharing': + post: + tags: + - Sharing + summary: Creates a new sharing + requestBody: + description: Contains the attributes for the sharing to be created. + content: + application/json: + schema: + type: object + properties: + userId: + type: integer + description: The id of the user that shares his fingerprints. + example: 42 + userSharedId: + $ref: '#/components/schemas/SharingUserId' + + responses: + 200: + description: Returns the success flag and the id for the newly created sharing. + content: + application/json: + schema: + type: object + properties: + success: + $ref: '#/components/schemas/Success' + sharingId: + $ref: '#/components/schemas/SharingId' + default: + $ref: '#/components/responses/Error' + +components: + parameters: + FingerprintId: + name: fingerprintId + in: path + required: true + schema: + $ref: '#/components/schemas/FingerprintId' + + SharingId: + name: sharingId + in: path + required: true + schema: + $ref: '#/components/schemas/SharingId' + + UserId: + name: userId + in: path + required: true + schema: + $ref: '#/components/schemas/UserId' + + responses: + Success: + description: Returns that the request could be handled successfully. + content: + application/json: + schema: + properties: + success: + $ref: '#/components/schemas/Success' + + Error: + description: Returns a JSON object that describes the error. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + schemas: + Error: + type: object + properties: + success: + type: boolean + description: Returns that the request couldn't be handled. + example: false + message: + type: string + description: Description of the error that occured. + example: Something extremely terrible happened! + + Success: + type: boolean + description: Returns if the request could be handled. + example: true + + UserId: + type: integer + description: The id of the user in question. + example: 42 + + Username: + type: string + description: The login name for the given user. + example: Kevin42 + + Password: + type: string + description: The password for the user login. + example: '12345' + + JabberAddress: + type: string + description: The address of the jabber account. + example: donalt@jabber.de + + EmailAddress: + type: string + description: The registered email address for the user. + example: kevin@gmail.com + + FingerprintId: + type: integer + description: The id that identifies the fingerprint. + example: 42 + readOnly: true + + Fingerprint: + type: string + description: The jabber fingerprint + example: '5BDF1668E59F2184582591699F55D9158DEF400A48772887A8F61531ED36B2A' + + SharingId: + type: integer + description: The id for the sharing. + example: 42 + readOnly: true + + SharingUserId: + type: integer + description: The id of the user who is allowed to display the fingerprints. + example: 25 \ No newline at end of file diff --git a/docs/api/v1.yaml b/docs/api/v1.yaml deleted file mode 100644 index e69de29..0000000