api.yaml

openapi: 3.0.3
info:
  title: WASAPhoto API Specification
  description: |
    This OpenAPI document describes the WASAPhoto project REST API.

    Keep in touch with your friends by sharing photos of special moments,
    thanks to WASAPhoto! Directly from your PC,
    you can upload your photos, and they will be visible to everyone
    who is following you.

    **Project details at [Project.pdf](http://gamificationlab.uniroma1.it/notes/Project.pdf)**
  version: "1.0.8"

servers:
  - url: http://localhost:8080
    description: Localhost development server

tags:
  - name: auth
    description: Authentication related operations
  - name: user
    description: User and ban related operations
  - name: follow
    description: Followings and followers related operations
  - name: photo
    description: Photo and file upload related operations
  - name: likes
    description: Likes related operations
  - name: comments
    description: Comments related operations

paths:
  /session:
    post:
      tags: ["auth"]
      summary: Logs in the user
      description: |
        If the user does not exist, it will be created,
        and an identifier is returned.
        If the user exists, the user identifier is returned.

        Later, the returned user identifier can be used an authentication token
        to authenticate subsequent requests.

        In case a new user is created, it'll use the given username as
        his/her first name, and the surname will be empty.

        You can later get the full user information with the appropriate endpoint.
      operationId: doLogin
      requestBody:
        description: User login details
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/LoginRequest" }
      responses:
        "200":
          description: User log-in action successful, user already exists
          content:
            application/json:
              schema: { $ref: "#/components/schemas/LoginResult" }
        "201":
          description: |
            User log-in action successful,
            user didn't exist and it has just been created.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/LoginResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
      security: []

  /users/:
    description: Users collection
    get:
      tags: ["user"]
      operationId: searchUsers
      summary: Search users
      description: |
        Search users by their username, or partial username.
        A text search is performed on usernames.

        A user must be logged in. This is required in order to hide
        other users who banned the one who is performing the search.
      parameters:
        - name: username
          in: query
          description: Username or part of the username to search
          required: true
          schema: { $ref: "#/components/schemas/Username" }
        - name: exactMatch
          in: query
          description: |
            It performs a search using the exact username match,
            not just the partial username search.
          required: false
          schema:
            description: Enable the exactMatch option
            type: boolean
            default: false
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200": { $ref: "#/components/responses/PaginatedUsersResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }

  /users/{userId}:
    description: Actions performed on a single user, identified by the given ID
    parameters:
      - $ref: "#/components/parameters/UserId"
    get:
      tags: ["user"]
      operationId: getUserProfile
      summary: Get user's profile details
      description: |
        Get user's profile details,
        not including the list of his/her photos,
        which can be requested using the dedicated endpoint.

        Who requests the user info must be authenticated,
        in order to detect if it's allowed to see other's information
        (e.g. banned or not).
      responses:
        "200":
          description: Get details about this user's profile
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
        "404":
          description: User with given ID doesn't exist
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }
    put:
      tags: ["user"]
      operationId: setMyDetails
      summary: Update user details
      description: |
        Update user details like name, surname, username, etc.
        You can only update your own details.
      requestBody:
        description: Fields to update on the specified user
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/User" }
      responses:
        "200":
          description: User fields have been updated successfully
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
        "409":
          description: A user with the requested new username already exists
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

  /users/{userId}/username:
    parameters:
      - $ref: "#/components/parameters/UserId"
    description: |
      Special resource which points to
      the username field of the currently logged in user.
    put:
      tags: ["user"]
      operationId: setMyUserName
      summary: Update username
      description: Update user's username. You are not allowed to edit others username.
      requestBody:
        description: New username to assign to the current user
        required: true
        content:
          text/plain:
            schema: { $ref: "#/components/schemas/Username" }
      responses:
        "200":
          description: User username has been updated successfully
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
        "409":
          description: A user with the requested new username already exists
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

  /users/{userId}/followers/:
    description: Actions on someone's followers
    parameters:
      - $ref: "#/components/parameters/UserId"
    get:
      tags: ["follow"]
      operationId: listFollowers
      summary: List someone's followers
      description: |
        List, with cursor pagination, all the followers of the specified user.

        You must be authenticated in order to be sure that you are allowed
        to see information about this user.
      parameters:
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200": { $ref: "#/components/responses/PaginatedUsersResult" }
        "404":
          description: A user with this ID doesn't exist
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

  /users/{userId}/followings/:
    parameters:
      - $ref: "#/components/parameters/UserId"
    get:
      tags: ["follow"]
      operationId: listFollowings
      summary: List someone's followings
      description: |
        List, with cursor pagination, all the followings of the specified user.

        You must be authenticated in order to be sure that you are allowed
        to see information about this user.
      parameters:
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200": { $ref: "#/components/responses/PaginatedUsersResult" }
        "404":
          description: A user with this ID doesn't exist
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

  /users/{userId}/followings/{followedId}:
    description: A resource to identify a follower.
    parameters:
      - $ref: "#/components/parameters/UserId"
      - name: followedId
        in: path
        required: true
        description: |
          Unique ID of the user to follow.
          If A wants to follow B, followedId = B's ID
        schema: { $ref: "#/components/schemas/ResourceId" }
    delete:
      tags: ["follow"]
      operationId: unfollowUser
      summary: Unfollow a user
      description: |
        Remove yourself as a follower
        of the user identified by the ID in the path.
      responses:
        "204":
          description: |
            You are not following this user anymore,
            or you wasn't following him/her in the first place (idempotent)
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }
    put:
      tags: ["follow"]
      operationId: followUser
      summary: Follow a user
      description: |
        Add the user you want to follow in the followings collection.

        You may not have the authorization to follow someone,
        for instance if the user you want to follow already banned you.
        Also, you cannot add followers to someone else's followings.
      responses:
        "201":
          description: You are now following this user.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UserFollow" }
        "200":
          description: You were already following this user (idempotent).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UserFollow" }
        "404":
          description: The user specified with "followedId" doesn't exist.
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

  /users/{userId}/bannedPeople/{blockedId}:
    description: Resource to indicate who blocked who.
    parameters:
      - $ref: "#/components/parameters/UserId"
      - name: blockedId
        required: true
        in: path
        description: The unique ID of the user to block
        schema: { $ref: "#/components/schemas/ResourceId" }
    put:
      tags: ["user"]
      operationId: banUser
      summary: Ban a user
      description: Ban another existing user. Banning someone will also make him unfollow you.
      responses:
        "201":
          description: User banned, and it wasn't before
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UserBan" }
        "200":
          description: User banned, but it already was
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UserBan" }
        "404":
          description: User to ban not found
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "409":
          description: You cannot ban yourself
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
    delete:
      tags: ["user"]
      operationId: unbanUser
      summary: Unban a user
      description: |
        Unban a previously banned user.
        You are only allowed to unban users for yourself.
      responses:
        "204":
          description: User unbanned or not banned in the first place.
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }

  /users/{userId}/photos/:
    description: Photos collection of a user
    parameters:
      - $ref: "#/components/parameters/UserId"
    get:
      tags: ["photo"]
      operationId: listUserPhotos
      summary: Get someone's photos
      description: List all photos of a user, using a paginated requests.

        You must be authenticated in order to be sure that you are allowed
        to see information about this user.
      parameters:
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200": { $ref: "#/components/responses/PaginatedPhotosResult" }
        "404":
          description: A user with this ID cannot be found
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

  /photos/:
    description: Photos collection
    post:
      tags: ["photo"]
      operationId: uploadPhoto
      summary: Upload photo
      description: |
        Upload a new photo to your personal account.
      requestBody:
        description: The binary image file to upload
        content:
          image/*:
            schema:
              description: Photo file to upload, directly as a binary file.
              # Schema indicated according to the official docs:
              # https://swagger.io/docs/specification/data-models/data-types/#file
              type: string
              minLength: 1
              maxLength: 20971520 # 20MB
              format: binary
      responses:
        "201":
          description: |
            The post was created.
            The image was successfully uploaded and elaborated.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Photo" }
        "415":
          description: The file sent cannot be processed as an image.
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "503":
          description: A third-party service required to fulfill the request is not available.
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }

  /photos/{photoId}:
    parameters:
      - $ref: "#/components/parameters/PhotoId"
    delete:
      tags: ["photo"]
      operationId: deletePhoto
      summary: Delete a photo
      description: |
        Delete an existing published post.
        A user can only delete his own photos.
      responses:
        "204":
          description: The post existed and it has just been deleted, or it didn't exist (idempotent).
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

  /photos/{photoId}/likes/{userId}:
    parameters:
      - $ref: "#/components/parameters/PhotoId"
      - $ref: "#/components/parameters/UserId"
    put:
      tags: ["likes"]
      operationId: likePhoto
      summary: Like a photo
      description: The specified user will leave a like on a photo
      responses:
        "201":
          description: Your like was added
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PhotoLike" }
        "200":
          description: Your like was already added
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PhotoLike" }
        "404":
          description: A post with this ID doesn't exist
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }
    delete:
      tags: ["likes"]
      operationId: unlikePhoto
      summary: Unlike a photo
      description: Remove a like from a photo
      responses:
        "204":
          description: Your like was removed
        "404":
          description: A post with this ID doesn't exist
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

  /photos/{photoId}/comments/:
    parameters:
      - $ref: "#/components/parameters/PhotoId"
    get:
      tags: ["comments"]
      operationId: getPhotoComments
      summary: List comments left on a photo
      description: |
        List all the comments users left on a photo,
        in reverse chronological order,
        using cursor pagination not to overwhelm the client.

        You must be logged in, because the author of the post may have banned you.
        In that case, you are not authorized to see.
      parameters:
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200": { $ref: "#/components/responses/PaginatedCommentsResult" }
        "404":
          description: A post with this ID doesn't exist
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

    post:
      tags: ["comments"]
      operationId: commentPhoto
      summary: Comment a photo
      description: |
        Leave a comment on a photo, if authorized.
        For instance, you cannot leave a comment
        under a photo of a user who banned you.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/NewComment" }
      responses:
        "201":
          description: Your comment was added
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Comment" }
        "404":
          description: A post with this ID doesn't exist
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

  /photos/{photoId}/comments/{commentId}:
    parameters:
      - $ref: "#/components/parameters/PhotoId"
      - $ref: "#/components/parameters/CommentId"
    delete:
      tags: ["comments"]
      operationId: uncommentPhoto
      summary: Delete a comment
      description: |
        Delete a comment from a photo.
        A comment can only be deleted by its author.
      responses:
        "204":
          description: Your comment was deleted.
        "404":
          description: A post with the given ID doesn't exist.
          content:
            text/plain:
              schema: { $ref: "#/components/schemas/Error" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

  /users/{userId}/stream:
    description: Resource of photos stream for a user
    parameters:
      - $ref: "#/components/parameters/UserId"
    get:
      tags: ["follow"]
      operationId: getMyStream
      summary: Get my own stream
      description: |
        Get my own post stream (you are not allowed to see others' stream),
        using cursor pagination.
        It will contain posts from the profiles you follow,
        in reverse chronological order.
      parameters:
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200": { $ref: "#/components/responses/PaginatedPhotosResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "500": { $ref: "#/components/responses/ServerError" }
        "401": { $ref: "#/components/responses/LoginError" }
        "403": { $ref: "#/components/responses/AuthorizationError" }

components:
  parameters:
    UserId:
      name: userId
      required: true
      in: path
      description: The unique ID of a user
      schema: { $ref: "#/components/schemas/ResourceId" }
    PhotoId:
      name: photoId
      required: true
      in: path
      description: The unique ID of a post, not the image file directly
      schema: { $ref: "#/components/schemas/ResourceId" }
    CommentId:
      name: commentId
      description: The unique ID of a comment
      required: true
      in: path
      schema: { $ref: "#/components/schemas/ResourceId" }
    PageCursor:
      name: pageCursor
      description: |
        In cursor pagination, this refers to
        the ID of the latest resource received by the client.
      required: false
      in: query
      schema: { $ref: "#/components/schemas/PageCursor" }

  responses:
    BadRequest:
      description: |
        The request was not compliant with the documentation
        (eg. missing fields, etc).
      content:
        text/plain:
          schema: { $ref: "#/components/schemas/Error" }
    ServerError:
      description: |
        An unexpected error occurred on the server
        while processing this request.
      content:
        text/plain:
          schema: { $ref: "#/components/schemas/Error" }
    LoginError:
      description: |
        Authentication is required to perform this action,
        and no *valid* authentication was included in this request.
      content:
        text/plain:
          schema: { $ref: "#/components/schemas/Error" }
    AuthorizationError:
      description: |
        A valid authentication is included in this request,
        but you are not authorized to perform this action.

        For instance, you are trying to modify someone else's data,
        or access to information about someone who banned you.
      content:
        text/plain:
          schema: { $ref: "#/components/schemas/Error" }

    PaginatedPhotosResult:
      description: |
        The current page was successfully returned
        and it may contain some photos.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/PaginatedPhotos" }
    PaginatedUsersResult:
      description: |
        The current page was successfully returned
        and it may contain some users.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/PaginatedUsers" }

    PaginatedCommentsResult:
      description: |
          The current page was successfully returned
          and it may contain some users.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/PaginatedComments" }

  schemas:
    Error:
      description: Result representing an error description
      type: string
      minLength: 0
      maxLength: 250
      readOnly: true

    ResourceId:
      description: The unique resource ID as a UUID string
      type: string
      example: "123e4567-e89b-12d3-a456-426614174000"
      minLength: 36
      maxLength: 36
      readOnly: true
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

    Username:
      description: User's personal and unique username
      type: string
      example: john_doe_42
      pattern: "^[a-z_0-9]+$"
      minLength: 3
      maxLength: 16

    LoginRequest:
      description: Current user to login
      type: object
      properties:
        username: { $ref: "#/components/schemas/Username" }

    LoginResult:
      type: object
      description: |
        Login result with auth details
        (the user ID to pass in Authorization as Bearer token).
      properties:
        userId: { $ref: "#/components/schemas/ResourceId" }

    User:
      description: |
        Representation of a user, with all the details useful in his/her profile.
        It won't directly include his/her photos, because they must be
        requested separately, using pagination.
      type: object
      properties:
        id: { $ref: "#/components/schemas/ResourceId" }
        name:
          description: User's name
          type: string
          example: John
          pattern: "^.*$"
          minLength: 2
          maxLength: 256
        surname:
          description: User's surname
          type: string
          minLength: 0
          maxLength: 256
          example: Doe
          pattern: "^.*?$"
          default: ""
        username:
          $ref: "#/components/schemas/Username"
        followersCount:
          description: Total count of the followers of a user
          type: integer
          readOnly: true
          minimum: 0
          example: 500
        followingsCount:
          description: Total count of the followings of a user
          type: integer
          readOnly: true
          minimum: 0
          example: 80
        postsCount:
          description: Total count of the posts of a user
          type: integer
          readOnly: true
          minimum: 0
          example: 12
        banned:
          description: |
            It indicates if the user performing this request
            has banned the user represented by this resource.
          type: boolean
          readOnly: true
          example: false
        following:
          description: |
            It indicates whether or not the user performing this request
            is currently following the user represented by this resource.
          type: boolean
          readOnly: true
          example: true

    DateTime:
      description: Standard datetime representation
      type: string
      format: date-time
      example: "2017-07-21T17:32:28Z"
      minLength: 20
      maxLength: 20
      readOnly: true

    StaticImageUrl:
      description: |
        The direct URL to the image file.

        It may also be stored on a different server,
        which can be dedicated to serve static resources,
        or maybe a CDN or may also be simply this server.

        The file can be cached and it's guaranteed to never change.
      type: string
      minLength: 10
      maxLength: 256
      readOnly: true
      example: https://static.example.com/img_1111_d404401c8c6495b206fc35c95e55a6d5.webp

    Photo:
      description: |
        A photo post, with aggregate information about likes and comments.
        Detailed comments can be requested separately using an appropriate paginated endpoint.
      type: object
      properties:
        id: { $ref: "#/components/schemas/ResourceId" }
        imageUrl: { $ref: "#/components/schemas/StaticImageUrl" }
        author: { $ref: "#/components/schemas/User" }
        publishDate: { $ref: "#/components/schemas/DateTime" }
        likesCount:
          description: Total count of the likes this post received
          type: integer
          minimum: 0
          example: 1200
          readOnly: true
        commentsCount:
          description: Total count of the comments this post received
          type: integer
          minimum: 0
          example: 300
          readOnly: true
        liked:
          description: |
            The current user liked this photo.
            If the request isn't authenticated, this will always be false.
          type: boolean
          readOnly: true

    NewComment:
      description: A new comment to publish
      type: object
      properties:
        text:
          description: Comment text
          type: string
          minLength: 1
          maxLength: 256
          example: Great post! Keep up the good work.
          pattern: ".+"

    Comment:
      description: A comment left on a post
      allOf:
        - type: object
          properties:
            id: { $ref: "#/components/schemas/ResourceId" }
            publishDate: { $ref: "#/components/schemas/DateTime" }
            author: { $ref: "#/components/schemas/User" }
        - $ref: "#/components/schemas/NewComment"

    PaginationInfo:
      type: object
      readOnly: true
      description: |
        Additional data necessary to handle
        paginated responses and subsequent requests.
      properties:
        nextPageCursor: { $ref: "#/components/schemas/PageCursor" }
        pageData:
          type: array
          minItems: 0
          maxItems: 20
          items:
            type: object
          description: Data of this page, if any

    PageCursor:
      type: string
      description: String to be sent as pageCursor in the subsequent request
      minLength: 1
      maxLength: 80
      nullable: true
      example: "MjFkMTM5ZmUtNWRjNi00OThkLWEyMTAtNmUyNDM1N2MwNmFhOzIwMjItMTEtMjFUMTE6NTM6MDha"
      pattern: "^[a-zA-Z0-9_-]+$"

    PaginatedComments:
      description: Current page of comments
      allOf:
        - $ref: "#/components/schemas/PaginationInfo"
        - description: Current selected page
          type: object
          readOnly: true
          properties:
            pageData:
              description: Comments of the current page
              type: array
              minItems: 0
              maxItems: 20
              items: { $ref: "#/components/schemas/Comment" }

    PaginatedPhotos:
      description: Current page of photos
      allOf:
        - $ref: "#/components/schemas/PaginationInfo"
        - description: Current selected page
          type: object
          readOnly: true
          properties:
            pageData:
              description: Photos of the current page
              type: array
              minItems: 0
              maxItems: 20
              items: { $ref: "#/components/schemas/Photo" }

    PaginatedUsers:
      description: Current page of users
      allOf:
        - $ref: "#/components/schemas/PaginationInfo"
        - description: Current selected page
          type: object
          readOnly: true
          properties:
            pageData:
              description: Users of the current page
              type: array
              minItems: 0
              maxItems: 20
              items: { $ref: "#/components/schemas/User" }

    UserFollow:
      description: Representation of the following of a user
      type: object
      readOnly: true
      properties:
        followingId: { $ref: "#/components/schemas/ResourceId" }
        followerId: { $ref: "#/components/schemas/ResourceId" }

    UserBan:
      description: Representation of the ban of a user
      type: object
      readOnly: true
      properties:
        bannedId: { $ref: "#/components/schemas/ResourceId" }
        bannerId: { $ref: "#/components/schemas/ResourceId" }

    PhotoLike:
      description: Representation of the like on a photo
      type: object
      readOnly: true
      properties:
        photoId: { $ref: "#/components/schemas/ResourceId" }
        userId: { $ref: "#/components/schemas/ResourceId" }

  securitySchemes:
    UserIdAuth:
      description: |
        User authentication with the user ID passed
        as it would be an authentication token.
        Of course, that's extremely insecure, but it's done
        according to the project specification.
      type: http
      scheme: bearer

# Apply security scheme globally, disabling it explicitly when unnecessary.
security:
  - UserIdAuth: []