openapi.yaml

openapi: 3.0.3
info:
  title: sf-microblog
  description: Specification of resources available on API Gateway in sf-microblog
  contact:
    name: Maksymilian Babarowski
    email: maksymilian@babarowski.pl
  license:
    name: MIT
  version: 1.0.0

paths:
  /post:
    get:
      description: Returns list of all publicly available posts sorted chronologically
      responses:
        200:
          description: A list of posts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/basicPost'
    post:
      description: Adds a new post
      responses:
        201:
          description: Newly added post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/post'
        400:
          description: Malformed request body
        401:
          description: No authorization token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/newPost'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/newPostWithMedia'
            encoding:
              postDetails:
                contentType: application/json
              mediaData:
                contentType: image/jpeg, image/png, image/gif, image/webp
  /post/{id}:
    get:
      description: Returns details of a single post matched by ID
      responses:
        200:
          description: Details of the post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/post'
        404:
          description: Post does not exist or has been deleted
    put:
      description: Updates post sent by an authorized user
      responses:
        200:
          description: Details of the updated post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/post'
        400:
          description: Malformed request body
        401:
          description: User is not authorized (not an author)
        404:
          description: Post does not exist or has been deleted
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/newPost'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/newPostWithMedia'
            encoding:
              postDetails:
                contentType: application/json
              mediaData:
                contentType: image/jpeg, image/png, image/gif, image/webp
    delete:
      description: Removes the post added by the user
      responses:
        204:
          description: Post removed
        401:
          description: Not authorized to remove this post (not an author)
        404:
          description: Post does not exist or has already been removed
    parameters:
      - name: id
        in: path
        description: ID of the post
        required: true
        schema:
          type: integer
          format: long
  /comment:
    post:
      description: Adds a new comment
      responses:
        200:
          description: Newly added comment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/comment'
        400:
          description: Malformed request body
        401:
          description: No authorization
        404:
          description: Post with specified ID does not exist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/newComment'
  /comment/{id}:
    delete:
      description: Removes the comment added by the user
      responses:
        204:
          description: Comment removed
        401:
          description: Unauthorized to remove the comment (not an author)
        404:
          description: Comment does not exist or has alread been removed
    put:
      description: Updated the comment added by the user
      responses:
        200:
          description: Details of an updated comment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/comment'
        400:
          description: Malformed request body
        401:
          description: User not authorized (not an author)
        404:
          description: Comment does not exist or has been deleted
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/newComment'
    parameters:
      - name: id
        in: path
        description: ID of the comment
        required: true
        schema:
          type: integer
          format: long
  /user:
    get:
      description: Gets details of an authenticated user
      responses:
        200:
          description: Details of an authenticated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userSummary'
        401:
          description: No authorization
  /user/{username}:
    get:
      description: Get publicly available details of an user
      responses:
        200:
          description: Details of an user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userDetails'
        404:
          description: User does not exist
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
  /avatar:
    put:
      description: Set avatar as authenticated user
      responses:
        204:
          description: Avatar successfully set
        400:
          description: Incorrect payload
      requestBody:
        required: true
        content:
          image/png:
            schema:
              type: string
              format: binary

  /avatar/{username}:
    get:
      description: Get avatar file of an user
      responses:
        200:
          description: Binary content of an avatar
          content:
            image/png:
              schema:
                type: string
                format: binary
        404:
          description: User has no avatar or user is not available
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string

components:
  schemas:
    post:
      description: Full details of a post
      type: object
      properties:
        id:
          description: Unique identifier of the post, started by 1 and autoincremented with each post and comment added
          type: integer
          format: long
        author:
          $ref: '#/components/schemas/basicUserDetails'
        title:
          description: Title of the post
          type: string
        textContent:
          description: Text content added in the post
          type: string
        comments:
          description: List of comments of a post
          type: array
          default: []
          items:
            $ref: '#/components/schemas/comment'
        date:
          description: Date and time when post was added
          type: string
          format: date-time
        imageId:
          description: ID of the image attached to the post
          type: string
      required:
        - id
        - author
        - title
        - textContent
        - date
    basicPost:
      description: Basic details of a post
      type: object
      properties:
        id:
          description: Unique identifier of the post, started by 1 and autoincremented with each post and comment added
          type: integer
          format: long
        author:
          $ref: '#/components/schemas/basicUserDetails'
        title:
          description: Title of the post
          type: string
        textContent:
          description: Text content added in the post
          type: string
        imageUrl:
          description: URL to the image attached to the post
          type: string
          format: url
          default: null
        commentsCount:
          description: Quantity of comments added to the post
          type: integer
          format: int32
        date:
          description: Date and time when post was added
          type: string
          format: date-time
      required:
        - id
        - author
        - title
        - textContent
        - commentsCount
        - date
    newPost:
      description: Details of a new posted to be added. Essentially post schema without auto-generated fields.
      type: object
      properties:
        title:
          description: Title of a new post
          type: string
        textContent:
          description: Text content of a new post
          type: string
      required:
        - title
        - textContent
    newPostWithMedia:
      type: object
      properties:
        postDetails:
          $ref: '#/components/schemas/newPost'
        mediaData:
          type: string
          format: binary
    comment:
      description: Full details of a comment
      type: object
      properties:
        id:
          description: Unique identifier of the comment, started by 1 and autoincremented with each post and comment added
          type: integer
          format: long
        author:
          $ref: '#/components/schemas/basicUserDetails'
        content:
          description: Content of a comment
          type: string
        date:
          description: Date and time when comment was added
          type: string
          format: date-time
      required:
        - id
        - author
        - content
        - date
    newComment:
      description: Details of newly added comment. Essentialy comment schema without auto-generated fields.
      type: object
      properties:
        postId:
          description: ID of the post comment is being added to
          type: integer
          format: long
        textContent:
          description: Content of the comment
          type: string
    basicUserDetails:
      description: Basic details of the user
      type: object
      properties:
        username:
          type: string
        avatar:
          description: URL pointing to the avatar used
          type: string
          default: null
      required:
        - username
    userSummary:
      description: All details of the user
      type: object
      properties:
        username:
          type: string
        avatar:
          description: URL pointing to the avatar used
          type: string
          default: null
        joined:
          description: Date and time of user account creation
          type: string
          format: date-time
      required:
        - username
        - joined
    userDetails:
      description: All details of the user and their recent activity
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/userSummary'
        posts:
          description: List of posts user has added
          type: array
          items:
            $ref: '#/components/schemas/basicPost'
          default: []
        comments:
          description: List of comments user has added
          type: array
          items:
            $ref: '#/components/schemas/comment'
          default: []
      required:
        - summary
    newUserDetails:
      description: User details to be updated
      type: object
      properties:
        avatar:
          description: URL of a new avatar image
          type: string