api-docs.yaml

openapi: 3.0.0
info:
  title: Social Media Backend API
  description: A comprehensive social media backend with user authentication, posts, comments, and likes functionality
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com

servers:
  - url: http://localhost:3000
    description: Development server
  - url: https://api.example.com
    description: Production server

tags:
  - name: Authentication
    description: User authentication and authorization
  - name: Posts
    description: Post management operations
  - name: Comments
    description: Comment operations
  - name: Likes
    description: Like operations

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        username:
          type: string
          example: johndoe
        email:
          type: string
          format: email
          example: john@example.com
        fullName:
          type: string
          example: John Doe
        bio:
          type: string
          nullable: true
          example: Software developer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    Post:
      type: object
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: My First Post
        content:
          type: string
          example: This is the content of my first post
        userId:
          type: integer
          example: 1
        author:
          $ref: "#/components/schemas/User"
        commentsCount:
          type: integer
          example: 5
        likesCount:
          type: integer
          example: 10
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    Comment:
      type: object
      properties:
        id:
          type: integer
          example: 1
        content:
          type: string
          example: Great post!
        userId:
          type: integer
          example: 2
        postId:
          type: integer
          example: 1
        author:
          $ref: "#/components/schemas/User"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    Like:
      type: object
      properties:
        id:
          type: integer
          example: 1
        userId:
          type: integer
          example: 1
        postId:
          type: integer
          example: 1
        user:
          $ref: "#/components/schemas/User"
        createdAt:
          type: string
          format: date-time

    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Error message
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string

    Pagination:
      type: object
      properties:
        currentPage:
          type: integer
          example: 1
        totalPages:
          type: integer
          example: 10
        totalItems:
          type: integer
          example: 100
        itemsPerPage:
          type: integer
          example: 10

paths:
  /:
    get:
      summary: Health check
      tags:
        - Health
      responses:
        "200":
          description: API is running
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Social Media API is running
                  version:
                    type: string
                    example: 1.0.0

  /api/auth/register:
    post:
      summary: Register a new user
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - email
                - password
                - fullName
              properties:
                username:
                  type: string
                  example: johndoe
                email:
                  type: string
                  format: email
                  example: john@example.com
                password:
                  type: string
                  format: password
                  example: SecurePass123!
                fullName:
                  type: string
                  example: John Doe
                bio:
                  type: string
                  example: Software developer
      responses:
        "201":
          description: User registered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      user:
                        $ref: "#/components/schemas/User"
                      token:
                        type: string
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/auth/login:
    post:
      summary: Login user
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: john@example.com
                password:
                  type: string
                  format: password
                  example: SecurePass123!
      responses:
        "200":
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      user:
                        $ref: "#/components/schemas/User"
                      token:
                        type: string
        "401":
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/auth/me:
    get:
      summary: Get current user
      tags:
        - Authentication
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Current user retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      user:
                        $ref: "#/components/schemas/User"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/posts:
    get:
      summary: Get all posts
      tags:
        - Posts
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Page number
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
          description: Items per page
      responses:
        "200":
          description: Posts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      posts:
                        type: array
                        items:
                          $ref: "#/components/schemas/Post"
                      pagination:
                        $ref: "#/components/schemas/Pagination"

    post:
      summary: Create a new post
      tags:
        - Posts
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - content
              properties:
                title:
                  type: string
                  example: My First Post
                content:
                  type: string
                  example: This is the content of my first post
      responses:
        "201":
          description: Post created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      post:
                        $ref: "#/components/schemas/Post"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/posts/{id}:
    get:
      summary: Get single post by ID
      tags:
        - Posts
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: Post ID
      responses:
        "200":
          description: Post retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      post:
                        $ref: "#/components/schemas/Post"
        "404":
          description: Post not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: Update a post
      tags:
        - Posts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: Post ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: Updated Title
                content:
                  type: string
                  example: Updated content
      responses:
        "200":
          description: Post updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      post:
                        $ref: "#/components/schemas/Post"
        "403":
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: Delete a post
      tags:
        - Posts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: Post ID
      responses:
        "200":
          description: Post deleted successfully
        "403":
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/comments/post/{postId}:
    get:
      summary: Get all comments for a post
      tags:
        - Comments
      parameters:
        - in: path
          name: postId
          required: true
          schema:
            type: integer
          description: Post ID
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Comments retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      comments:
                        type: array
                        items:
                          $ref: "#/components/schemas/Comment"
                      pagination:
                        $ref: "#/components/schemas/Pagination"

    post:
      summary: Add a comment to a post
      tags:
        - Comments
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: postId
          required: true
          schema:
            type: integer
          description: Post ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  example: Great post!
      responses:
        "201":
          description: Comment added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      comment:
                        $ref: "#/components/schemas/Comment"

  /api/likes/post/{postId}:
    post:
      summary: Like a post
      tags:
        - Likes
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: postId
          required: true
          schema:
            type: integer
          description: Post ID
      responses:
        "201":
          description: Post liked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      likesCount:
                        type: integer

    delete:
      summary: Unlike a post
      tags:
        - Likes
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: postId
          required: true
          schema:
            type: integer
          description: Post ID
      responses:
        "200":
          description: Post unliked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      likesCount:
                        type: integer

    get:
      summary: Get post likes count and list
      tags:
        - Likes
      parameters:
        - in: path
          name: postId
          required: true
          schema:
            type: integer
          description: Post ID
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Likes retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      likesCount:
                        type: integer
                      likes:
                        type: array
                        items:
                          $ref: "#/components/schemas/Like"
                      pagination:
                        $ref: "#/components/schemas/Pagination"