OpenAPI documentation added

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