openapi: 3.0.3
info:
  version: v1.0.3
  title: LE-KO Feed Posts
  license:
    name: private
    url: https:/le-ko.deggex.com
  contact:
    email: denis@deggex.awsapps.com
  description: LE-KO Feed Posts
servers:
  - url: https://booking-{env}.le-ko.deggex.com/{basePath}
    description: Feed Posts endpoint
    variables:
      basePath:
        default: v1
      env:
        default: dev
security:
  - bearerHttpAuthentication: []
tags:
  - name: posts
    description: Posts
paths:
  /feeds/{userId}/posts.get:
    post:
      operationId: getFollowedPosts
      summary: .../posts.get
      description: ✨ Get specific user's posts and followed by specific user posts
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/ParamPage'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostGet'
      responses:
        '200':
          description: User's and followed Posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostsPage'
        '400':
          $ref: '#/components/responses/400'
  /feeds/{userId}/posts:
    get:
      operationId: getAllPosts
      summary: .../posts
      description: ✨ Get all User Posts
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/ParamPage'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of User Posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostsPage'
        '400':
          $ref: '#/components/responses/400'
    post:
      operationId: createPost
      summary: .../posts
      description: ✨ Create new Post
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCreate'
      responses:
        '200':
          description: User Post has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          $ref: '#/components/responses/400'
  /feeds/{userId}/posts/{postId}:
    get:
      operationId: getPostById
      summary: .../posts/{id}
      description: ✨ Get User post by id
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/PostId'
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: User Post details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
    put:
      operationId: updatePost
      summary: .../posts/{id}
      description: ✨ Update User Post
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/PostId'
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostUpdate'
      responses:
        '200':
          description: User Post has been updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
    delete:
      operationId: deletePost
      summary: .../posts/{id}
      description: ✨ Delete User Post
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/PostId'
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Post has been deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  postId:
                    $ref: '#/components/schemas/PostId'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
  /feeds/{userId}/posts/{postId}/photos:
    post:
      operationId: createPhoto
      summary: .../posts/{id}/photos
      description: ✨ Create new Post Photo.
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/PostId'
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhotosCreate'
      responses:
        '200':
          description: Post Photo has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Photos'
        '400':
          $ref: '#/components/responses/400'
  /feeds/{userId}/posts/{postId}/photos/{photoId}:
    delete:
      operationId: deletePhoto
      summary: .../posts/{id}/photos/{id}
      description: ✨ Delete Post Photo by id.
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/PostId'
        - $ref: '#/components/parameters/PhotoId'
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Post Photo has been deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  photoId:
                    $ref: '#/components/schemas/PhotoId'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
  /feeds/{userId}/posts/{postId}/likes:
    get:
      operationId: getAllPostLikes
      summary: .../posts/{id}/likes
      description: ✨ Get Post Likes
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/PostId'
        - $ref: '#/components/parameters/ParamPage'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Post Likes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LikesPage'
        '400':
          $ref: '#/components/responses/400'
  /feeds/{userId}/posts/{postId}/like:
    put:
      operationId: togglePostLike
      summary: .../posts/{id}/like
      description: ✨ Post like toggling
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/PostId'
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Post Like has been changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Like'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
  /feeds/{userId}/posts/{postId}/hide:
    put:
      operationId: togglePostHide
      summary: .../posts/{id}/hide
      description: ✨ Toggle Post hide from all or specific users
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/PostId'
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Hide'
      responses:
        '200':
          description: Post hiding has been changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HideResponse'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
  /feeds/{userId}/posts/{postId}/seen:
    put:
      operationId: markPostSeen
      summary: Mark a single post as seen
      description: ✨ Mark a single post as seen by the specified user
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/PostId'
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '204':
          description: Post marked as seen successfully
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /feeds/posts/{postId}/reports:
    post:
      operationId: createPostReport
      summary: Report a post
      description: ✨ Submit a report for inappropriate or problematic post content
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/PostId'
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReportRequest'
      responses:
        '201':
          description: Report created successfully
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
  /feeds/posts/seen:
    post:
      operationId: markPostsSeen
      summary: Mark posts as seen
      description: ✨ Mark multiple posts as seen by the current user (batch operation)
      tags:
        - posts
      parameters:
        - $ref: '#/components/parameters/CurrentUserId'
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkPostsSeenRequest'
      responses:
        '204':
          description: Posts marked as seen successfully
        '400':
          $ref: '#/components/responses/400'
components:
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer token using a JWT
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    UserId:
      type: string
      example: 00000000-0000-1000-9000-55f01dda9dd0
      description: User ID
      format: uuid
    PageNumber:
      type: integer
      description: Page number
      example: 0
      minimum: 0
      default: 0
    PageLimit:
      type: integer
      description: Page limit
      default: 10
      minimum: 1
      maximum: 100
      example: 10
    PostGet:
      type: object
      required:
        - recommendedPostIds
        - followedUserIds
      properties:
        recommendedPostIds:
          type: array
          items:
            type: string
            format: uuid
        followedUserIds:
          type: array
          items:
            $ref: '#/components/schemas/UserId'
          description: Followed User IDs
    Count:
      type: integer
      description: Page entries count
      example: 10
    CurrentPage:
      type: integer
      deprecated: true
      description: Current page
      example: 0
      minimum: 0
      default: 0
    PageSize:
      type: integer
      deprecated: true
      description: Page size
      default: 10
      minimum: 1
      maximum: 100
      example: 10
    TotalCount:
      type: integer
      description: Total count
      default: 0
      minimum: 0
      example: 1000
    Page:
      type: object
      required:
        - count
        - page
        - limit
        - total
      properties:
        data:
          type: array
          items:
            type: object
        count:
          $ref: '#/components/schemas/Count'
        currentPage:
          $ref: '#/components/schemas/CurrentPage'
        page:
          $ref: '#/components/schemas/PageNumber'
        pageSize:
          $ref: '#/components/schemas/PageSize'
        limit:
          $ref: '#/components/schemas/PageLimit'
        total:
          $ref: '#/components/schemas/TotalCount'
    PostId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Post ID
      format: uuid
    LocationId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Location or Address ID
      format: uuid
    Location:
      type: object
      required:
        - locationId
        - formattedAddress
      properties:
        locationId:
          $ref: '#/components/schemas/LocationId'
        formattedAddress:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
    PhotoId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Photo ID
      format: uuid
    DateTime:
      type: string
      format: date-time
      description: Date and time in RFC-3339
      example: '2024-11-29T12:09:53+00:00'
    Photo:
      type: object
      required:
        - postId
        - photoId
        - createdAt
      properties:
        postId:
          $ref: '#/components/schemas/PostId'
        photoId:
          $ref: '#/components/schemas/PhotoId'
        createdAt:
          $ref: '#/components/schemas/DateTime'
    PostMention:
      type: object
      properties:
        mentionedUserId:
          type: string
          format: uuid
        mentionText:
          type: string
      required:
        - mentionedUserId
        - mentionText
    Post:
      type: object
      required:
        - postId
        - userId
        - text
        - likeCount
        - commentCount
        - photoCount
        - likedByUser
        - commentedByUser
        - edited
        - hidden
        - photos
        - mentions
        - createdAt
        - updatedAt
      properties:
        postId:
          $ref: '#/components/schemas/PostId'
        userId:
          $ref: '#/components/schemas/UserId'
        location:
          $ref: '#/components/schemas/Location'
        text:
          type: string
        likeCount:
          type: integer
        commentCount:
          type: integer
        photoCount:
          type: integer
        likedByUser:
          type: boolean
        commentedByUser:
          type: boolean
        edited:
          type: boolean
        hidden:
          type: boolean
        photos:
          type: array
          items:
            $ref: '#/components/schemas/Photo'
        mentions:
          type: array
          items:
            $ref: '#/components/schemas/PostMention'
        createdAt:
          $ref: '#/components/schemas/DateTime'
        updatedAt:
          $ref: '#/components/schemas/DateTime'
    PostsPage:
      type: object
      allOf:
        - $ref: '#/components/schemas/Page'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Post'
    Error:
      type: object
      required:
        - code
        - message
        - endpoint
        - requestId
      properties:
        code:
          type: string
          description: Error unique code
          enum:
            - validation
            - internal
            - oops
            - unexpected
            - tooManyRequests
            - notFound
            - unauthorized
            - forbidden
        message:
          type: string
          description: Error message
        endpoint:
          type: string
        requestId:
          type: string
    Errors:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    PostText:
      type: string
      example: Lorem ipsum
      description: Post text
      format: text
      maxLength: 2000
    PostCreate:
      type: object
      required:
        - text
      properties:
        locationId:
          $ref: '#/components/schemas/LocationId'
        text:
          $ref: '#/components/schemas/PostText'
        mentions:
          type: array
          items:
            $ref: '#/components/schemas/PostMention'
    PostUpdate:
      type: object
      required:
        - text
      properties:
        locationId:
          $ref: '#/components/schemas/LocationId'
        text:
          $ref: '#/components/schemas/PostText'
    PhotosCreate:
      type: object
      required:
        - photoIds
      properties:
        photoIds:
          type: array
          items:
            $ref: '#/components/schemas/PhotoId'
    Photos:
      type: object
      required:
        - photos
      properties:
        photos:
          type: array
          items:
            $ref: '#/components/schemas/Photo'
    LikeId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Like ID
      format: uuid
    CommentId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Comment ID
      format: uuid
    LikeUserId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Like User ID
      format: uuid
    Like:
      type: object
      required:
        - postId
        - likeUserId
        - isLiked
      properties:
        likeId:
          $ref: '#/components/schemas/LikeId'
        postId:
          $ref: '#/components/schemas/PostId'
        commentId:
          $ref: '#/components/schemas/CommentId'
        likeUserId:
          $ref: '#/components/schemas/LikeUserId'
        isLiked:
          type: boolean
        createdAt:
          $ref: '#/components/schemas/DateTime'
    LikesPage:
      type: object
      allOf:
        - $ref: '#/components/schemas/Page'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Like'
    Hide:
      type: object
      required:
        - hideFromAll
        - hideFromUserIds
      properties:
        hideFromAll:
          type: boolean
        hideFromUserIds:
          type: array
          items:
            $ref: '#/components/schemas/UserId'
    HideResponse:
      type: object
      required:
        - hideFromAll
        - hiddenFromUserIds
        - unHiddenFromUserIds
      properties:
        hideFromAll:
          type: boolean
        hiddenFromUserIds:
          type: array
          items:
            $ref: '#/components/schemas/UserId'
        unHiddenFromUserIds:
          type: array
          items:
            $ref: '#/components/schemas/UserId'
    CreateReportRequest:
      type: object
      properties:
        description:
          type: string
          nullable: true
          description: Optional text description explaining why this content is being reported
          maxLength: 1000
    SeenPostItem:
      type: object
      required:
        - postId
        - postOwnerId
      properties:
        postId:
          $ref: '#/components/schemas/PostId'
        postOwnerId:
          $ref: '#/components/schemas/UserId'
    MarkPostsSeenRequest:
      type: object
      required:
        - posts
      properties:
        posts:
          type: array
          items:
            $ref: '#/components/schemas/SeenPostItem'
  parameters:
    CurrentUserId:
      name: x-current-user-id
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/UserId'
    UserId:
      name: userId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UserId'
    ParamPage:
      name: page
      required: false
      in: query
      schema:
        $ref: '#/components/schemas/PageNumber'
    Limit:
      name: limit
      required: false
      in: query
      schema:
        $ref: '#/components/schemas/PageLimit'
    TraceparentHeader:
      name: traceparent
      in: header
      required: false
      description: W3C Trace Context traceparent header for request tracing
      schema:
        type: string
        pattern: ^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$
        example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
    PostId:
      name: postId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/PostId'
    PhotoId:
      name: photoId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/PhotoId'
  responses:
    '400':
      description: Bad Request, the request is not valid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
            example:
              errors:
                - code: 400
                  message: The request is not valid
    '403':
      description: Forbidden, you are not allowed to perform this action
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
            example:
              errors:
                - code: 403
                  message: You are not allowed to perform this action
    '404':
      description: Not found, the resource you are looking for does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
            example:
              errors:
                - code: 404
                  message: Resource not found