api: User Management & Authentication (#51)

.redocly.lint-ignore.yaml

@@ -0,0 +1,58 @@
+# This file instructs Redocly's linter to ignore the rules contained for specific parts of your API.
+# See https://redoc.ly/docs/cli/ for more information.
+openapi/karman.yaml:
+  spec:
+    - >-
+      #/components/securitySchemes/OAuth2/flows/urn:ietf:params:oauth:grant-type:token-exchange
+openapi/tags/auth.yaml:
+  operation-4xx-problem-details-rfc7807:
+    - '#/components/responses/TokenError'
+  path-segment-plural:
+    - '#/paths/~1auth~1token'
+openapi/tags/songs.yaml:
+  operation-4xx-problem-details-rfc7807:
+    - '#/components/schemas/SongNotFoundError/allOf/1/properties/type'
+    - '#/components/schemas/SongNotFoundError/allOf/1/properties/title'
+    - >-
+      #/components/responses/UploadSongCannotBeModified/content/application~1problem+json/schema/allOf/1/properties/type
+    - >-
+      #/components/responses/UploadSongCannotBeModified/content/application~1problem+json/schema/allOf/1/properties/title
+    - '#/components/schemas/InvalidTXTError/allOf/1/properties/type'
+    - '#/components/schemas/InvalidTXTError/allOf/1/properties/title'
+openapi/tags/media.yaml:
+  operation-4xx-problem-details-rfc7807:
+    - '#/components/schemas/FileNotFoundError/allOf/1/properties/type'
+    - '#/components/schemas/FileNotFoundError/allOf/1/properties/title'
+openapi/common/problem-details.yaml:
+  operation-4xx-problem-details-rfc7807:
+    - >-
+      #/components/responses/UnprocessableEntity/content/application~1problem+json/schema/allOf/1/properties/type
+    - >-
+      #/components/responses/UnprocessableEntity/content/application~1problem+json/schema/allOf/1/properties/title
+openapi/tags/uploads.yaml:
+  operation-4xx-problem-details-rfc7807:
+    - '#/components/schemas/UploadNotFoundError/allOf/1/properties/type'
+    - '#/components/schemas/UploadNotFoundError/allOf/1/properties/title'
+    - >-
+      #/components/responses/InvalidPathOrUUID/content/application~1problem+json/schema/oneOf/1/allOf/1/properties/type
+    - >-
+      #/components/responses/InvalidPathOrUUID/content/application~1problem+json/schema/oneOf/1/allOf/1/properties/title
+    - >-
+      #/components/responses/FileOrUploadNotFound/content/application~1problem+json/schema/oneOf/1/allOf/1/properties/type
+    - >-
+      #/components/responses/FileOrUploadNotFound/content/application~1problem+json/schema/oneOf/1/allOf/1/properties/title
+    - '#/components/responses/UploadStateError'
+openapi/tags/user.yaml:
+  operation-4xx-problem-details-rfc7807:
+    - >-
+      #/components/responses/UsernameNotAvailable/content/application~1problem+json/schema/allOf/1/properties/type
+    - >-
+      #/components/responses/UsernameNotAvailable/content/application~1problem+json/schema/allOf/1/properties/title
+    - >-
+      #/components/responses/UserNotFound/content/application~1problem+json/schema/allOf/1/properties/type
+    - >-
+      #/components/responses/UserNotFound/content/application~1problem+json/schema/allOf/1/properties/title
+    - >-
+      #/paths/~1v1~1users~1{id}~1email/post/responses/409/content/application~1problem+json/schema/allOf/1/properties/type
+    - >-
+      #/paths/~1v1~1users~1{id}~1email/post/responses/409/content/application~1problem+json/schema/allOf/1/properties/title

Makefile

@@ -13,7 +13,8 @@ build/openapi.yaml: .redocly.yaml $(OPENAPI_FILES)
 	@echo "Build OpenAPI Document"
 	@redocly join --output "$@" $(OPENAPI_SPECS)
 	@echo "Inserting Tag Groups"
-	@yq -i '.x-tagGroups = ($(shell yq -j .x-tagGroups < ./openapi/karman.yaml))' "$@"
+	@yq -i '.x-tagGroups = ($(shell yq -o=json .x-tagGroups < ./openapi/karman.yaml))' "$@"
+	@yq -i '.security = ($(shell yq -o=json .security < ./openapi/karman.yaml))' "$@"
 
 build/openapi.html: build/openapi.yaml
 	@echo "Build HTML Documentation"

openapi/common/pagination.yaml

@@ -2,7 +2,11 @@ openapi: 3.0.3
 info:
   title: Pagination Schema
   version: v1
+
+
 paths: {}
+
+
 components:
   parameters:
     limit:
@@ -23,6 +27,7 @@ components:
         minimum: 0
         maximum: 100
         example: 50
+
     offset:
       in: query
       name: offset
@@ -36,6 +41,8 @@ components:
         default: 0
         minimum: 0
         example: 25
+
+
   headers:
     Pagination-Count:
       description: |-
@@ -45,13 +52,15 @@ components:
         type: integer
         example: 25
       required: true
+
     Pagination-Offset:
       description: |-
         The index of the first returned element within the collection of all result elements.
       schema:
         type: integer
         example: 513
       required: true
+
     Pagination-Limit:
       description: |-
         The result size limit specified in the request.
@@ -60,6 +69,7 @@ components:
         default: 25
         example: 35
       required: true
+
     Pagination-Total:
       description: |-
         The total number of elements in the result (not only the results contained in the items).

openapi/common/problem-details.yaml

@@ -2,7 +2,11 @@ openapi: 3.0.3
 info:
   title: Error Schemas
   version: v1
+
+
 paths: {}
+
+
 components:
   schemas:
     ProblemDetails:
@@ -13,6 +17,7 @@ components:
           Unless documented these additional fields should not be relied upon.
       description: |-
         A problem details object as specified in [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807).
+      required: [ status ]
       properties:
         type:
           type: string
@@ -46,6 +51,7 @@ components:
             It may or may not yield further information if dereferenced.
             This field is usually absent but may be used for tracing information.
           example: "/traces/481CF77B-3099-445C-A789-58F997233681"
+
     InvalidUUIDError:
       title: Invalid UUID
       example:
@@ -54,6 +60,7 @@ components:
         status: 400
       allOf:
         - $ref: "#/components/schemas/ProblemDetails"
+
     BadRequestError:
       title: Bad Request Body
       example:
@@ -62,6 +69,29 @@ components:
         instance: "/traces/481CF77B-3099-445C-A789-58F997233681"
       allOf:
         - $ref: "#/components/schemas/ProblemDetails"
+
+    PermissionDeniedError:
+      title: PermissionDenied
+      example:
+        type: "codello.dev/karman/problems/permission-denied"
+        title: "Permission Denied"
+        status: 403
+        detail: "You must be an administrator to perform this action."
+      allOf:
+        - $ref: "#/components/schemas/ProblemDetails"
+
+
+    EndpointDisabledError:
+      title: Endpoint Disabled
+      example:
+        type: "codello.dev/karman/problems/endpoint-disabled"
+        title: "Endpoint Disabled"
+        status: 403
+        detail: "This feature has been disabled by the server administrator."
+      allOf:
+        - $ref: "#/components/schemas/ProblemDetails"
+
+
   responses:
     BadRequest:
       x-summary: Bad Request
@@ -74,6 +104,7 @@ components:
         application/problem+json:
           schema:
             $ref: "#/components/schemas/BadRequestError"
+
     InvalidUUID:
       x-summary: Invalid UUID
       description: |-
@@ -82,6 +113,7 @@ components:
         application/problem+json:
           schema:
             $ref: "#/components/schemas/InvalidUUIDError"
+
     BadRequestOrInvalidUUID:
       x-summary: Bad Request
       description: |-
@@ -97,6 +129,37 @@ components:
             oneOf:
               - $ref: "#/components/schemas/BadRequestError"
               - $ref: "#/components/schemas/InvalidUUIDError"
+
+    Unauthorized:
+      x-summary: Unauthorized
+      description: |-
+        The endpoint requires authentication, but a valid authentication token was not provided.
+      headers:
+        WWW-Authenticate:
+          schema:
+            type: string
+            enum: [ "Bearer"]
+          description: |-
+            This header contains information about the supported authentication schemes for this endpoint.
+      content:
+        application/problem+json:
+          schema:
+            example:
+              title: "Unauthorized"
+              status: 401
+              instance: "/traces/481CF77B-3099-445C-A789-58F997233681"
+            allOf:
+              - $ref: "#/components/schemas/ProblemDetails"
+
+    PermissionDenied:
+      x-summary: Permission Denied
+      description: |-
+        This error indicates that the user performing the request does not have the required permissions.
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/PermissionDeniedError"
+
     UnprocessableEntity:
       x-summary: Unprocessable Entity
       description: |-
@@ -115,18 +178,20 @@ components:
               title: "Unprocessable Entity"
               status: 422
               instance: "/traces/481CF77B-3099-445C-A789-58F997233681"
+              fields:
+                medley.medleyStartBeat: "number expected"
             allOf:
               - $ref: "#/components/schemas/ProblemDetails"
               - type: object
                 properties:
-                  field:
-                    type: string
-                    example: "medley.medleyStartBeat"
+                  fields:
+                    type: object
+                    additionalProperties: { type: string }
                     description: |-
                       A `Unprocessable Entity` response may or may not contain information about the JSON field that caused the error.
-                      The value of this property is the path to the field causing the error.
                       
-                      The `fields` object might contain a mapping from field paths to error messages.
+                      The value of this property is a mapping from field paths to error messages.
+
     UnexpectedError:
       x-summary: Unexpected Error
       description: |-
@@ -141,6 +206,7 @@ components:
               instance: "/traces/481CF77B-3099-445C-A789-58F997233681"
             allOf:
               - $ref: "#/components/schemas/ProblemDetails"
+
     UnsupportedMediaType:
       x-summary: Unsupported Media Type
       description: |-
@@ -153,4 +219,4 @@ components:
               status: 415
               instance: "/traces/481CF77B-3099-445C-A789-58F997233681"
             allOf:
-              - $ref: "#/components/schemas/ProblemDetails"
+              - $ref: "#/components/schemas/ProblemDetails"

openapi/karman.yaml

@@ -46,11 +46,44 @@ info:
   license:
     name: MIT
     url: https://opensource.org/license/mit/
+
+
 paths: {}
+
+
 x-tagGroups:
   - name: Library Management
     tags:
+      - auth
       - song
       - media
       - upload
-# TODO: ETag support (and If-None-Match, If-Modified-Since)
+      - user
+
+
+security:
+  - OAuth2: []
+
+
+components:
+  securitySchemes:
+    OAuth2:
+      type: oauth2
+      description: |-
+        In order to access this endpoint you must provide a valid `Bearer` token
+        in the `Authorization` header.
+        
+        See the [`/auth/token`](#tag/auth/operation/createToken) endpoint for more information on how to acquire a token.
+      flows:
+        # noinspection YAMLSchemaValidation
+        urn:ietf:params:oauth:grant-type:token-exchange: {}
+          # Semantically these should be uncommented.
+          # However, visually Redoc only shows the refreshUrl which might be misleading.
+          # The urls from the password flow display in a way that it can also be applied to this flow.
+
+          # tokenUrl: /auth/token
+          # refreshUrl: /auth/token
+        password:
+          tokenUrl: /auth/token
+          refreshUrl: /auth/token
+          scopes: {}