project-knedita/swagger.yaml

openapi: 3.0.0

info:
  version: 0.0.1
  title: Project Knedita - Documentation
  description: An open source social media project.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

tags:
  - name: Users
    description: User related endpoints
  - name: Posts
    description: Post related endpoints
  - name: Comments
    description: Comment related endpoints

paths:
  # Users - GET paths
  /user/info:
    get:
      summary: Returns information about a specific user.
      description: Returns information about a specific user (profile picture, display name, etc).
      tags:
        - Users
      parameters:
        - name: u
          in: query
          required: true
          schema:
            type: string
            example: 'cookie'
      responses:
        '200':
          description: An object containing all user information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  profileImage:
                    type: string
                  displayName:
                    type: string
                  username:
                    type: string
                  createdAt:
                    type: string
                  followers:
                    type: integer
                    example: 0
                  following:
                    type: integer
                    example: 0
                  posts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        content:
                          type: string
                        createdAt:
                          type: string
                        updatedAt:
                          type: string
                  likedPosts:
                    type: array
                    items:
                      type: object
                      properties:
                        postId:
                          type: string
        '400':
          $ref: '#/components/responses/BadRequest'

  /user/fetch-posts:
    get:
      summary: Returns all posts made by specific user.
      description: Returns all posts made by specific user.
      tags:
        - Users
      parameters:
        - name: u
          in: query
          required: true
          schema:
            type: string
            example: 'cookie'
      responses:
        '200':
          description: An array of objects containing post information (returns an empty array if no posts were found).
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    content:
                      type: string
                    createdAt:
                      type: string
                    updatedAt:
                      type: string
                    author:
                      type: object
                      properties:
                        displayName:
                          type: string
                        username:
                          type: string
                        profileImage:
                          type: string
                    _count:
                      type: object
                      properties:
                        likes:
                          type: integer
                        comments:
                          type: integer

  /user/search:
    get:
      summary: Returns user with the provided username.
      description: Returns up to 10 users with the provided username.
      tags:
        - Users
      parameters:
        - name: u
          in: query
          required: true
          schema:
            type: string
            example: 'cookie'
      responses:
        '200':
          description: An array of objects containing basic user information (returns an empty array if no users were found).
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    displayName:
                      type: string
                    username:
                      type: string
                    profileImage:
                      type: string

  /user/auth:
    post:
      summary: Authenticate user
      description: Authenticate the provided user
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Returns authentication token and user's username
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                  user:
                    type: string
                    example: 'cookie'
        '400':
          $ref: '#/components/responses/BadRequest'

  /user/signup:
    post:
      summary: Creates a new user
      description: Creates a new user
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                email:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: An object containing basic user information
          content:
            application/json:
              schema:
                type: object
                properties:
                  displayName:
                    type: string
                  username:
                    type: string
                  createdAt:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'

  # Users - POST paths
  /user/delete:
    post:
      summary: Deletes an authenticated user
      description: Deletes an authenticated user
      tags:
        - Users
      security:
        - JWTAuth: []
      responses:
        '200':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /user/follow-user:
    post:
      summary: Follows a user
      description: Follows a user
      security:
        - JWTAuth: []
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userToFollow:
                  type: string
                  example: 'cookie1'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /user/like-comment:
    post:
      summary: Likes a post comment
      description: Likes a post comment
      security:
        - JWTAuth: []
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                commentId:
                  type: string
                  example: '7fb6e6e7-8e37-4814-bab6-36e5aa35796c'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /user/like-post:
    post:
      summary: Likes a post
      description: Likes a post
      security:
        - JWTAuth: []
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                postId:
                  type: string
                  example: f4e2b724-f226-4674-8e3b-0c0c512b09d4
      responses:
        '200':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /user/me:
    post:
      summary: Returns basic information about the authenticated user
      description: Returns basic information about the authenticated user
      security:
        - JWTAuth: []
      tags:
        - Users
      responses:
        '200':
          description: Authenticated user information
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  profileImage:
                    type: string
                  displayName:
                    type: string
                  username:
                    type: string
                  createdAt:
                    type: string
                  followers:
                    type: integer
                    example: 0
                  following:
                    type: integer
                    example: 0
                  posts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        content:
                          type: string
                        createdAt:
                          type: string
                        updatedAt:
                          type: string
                  likedPosts:
                    type: array
                    items:
                      type: object
                      properties:
                        postId:
                          type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # Users - PUT paths
  /user/profile-picture/upload:
    put:
      summary: Uploads a profile picture for the authenticated user
      description: Uploads a profile picture for the authenticated user
      security:
        - JWTAuth: []
      tags:
        - Users
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  profileImage:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /user/update-name:
    put:
      security:
        - JWTAuth: []
      tags:
        - Users

  /user/update-email:
    put:
      security:
        - JWTAuth: []
      tags:
        - Users

  /user/update-password:
    put:
      security:
        - JWTAuth: []
      tags:
        - Users

  # Posts - GET paths
  /post/info:
    get:
      tags:
        - Posts

  /post/fetch-likes:
    get:
      tags:
        - Posts

  # Posts - POST paths
  /post/create:
    post:
      tags:
        - Posts

  /post/delete:
    post:
      tags:
        - Posts

  # Posts - PUT paths
  /post/update:
    put:
      tags:
        - Posts

  # Comments - GET paths
  /comment/info:
    get:
      tags:
        - Comments

  /comment/fetch-likes:
    get:
      tags:
        - Comments

  # Comments - POST paths
  /comment/create:
    post:
      tags:
        - Comments

  /comment/delete:
    post:
      tags:
        - Comments

  # Comments - PUT paths
  /comment/update:
    put:
      tags:
        - Comments

components:
  securitySchemes:
    JWTAuth:
      type: http
      scheme: bearer
      description: JWT Authentication via Authorization header
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    EmptyResponse:
      description: Successful Response (empty response)
      content:
        application/json:
          schema:
            type: object
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string