blog-api-1.0.0

blog-api-1.0.0

plugin name: OpenAPI (Swagger) Editor

---
openapi: 3.0.0
info:
  title: FSArmy - My Blog API
  description: "This is the first professional api project we creating in full-stack army. This is a simple blog api application where anyone can create a new account, login to their system and create articles that will be visible publicly."
  contact:
    name: FS Army
    url: https://fsarmy.com
    email: support@fsarmy.com
  version: 1.0.0
servers:
- url: https://virtserver.swaggerhub.com/stacklearner/fs-army-my-blog-api/1.0.0
  description: SwaggerHub API Auto Mocking
- url: http://localhost:4000/api/v1
  description: Dev
tags:
- name: Auth
  description: Authentication Endpoints (public)
- name: Article
  description: Article Endpoints (public + private)
- name: Comment
  description: Comment Endpoints (Private)
- name: User
  description: User Endpoints (admin only)
paths:
  /auth/signup:
    post:
      tags:
      - Auth
      description: create a new account
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/auth_signup_body'
      responses:
        "201":
          description: Signup successul
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_201'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
  /auth/signin:
    post:
      tags:
      - Auth
      description: Login to your account
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/auth_signin_body'
      responses:
        "200":
          description: Signin successul
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
  /articles:
    get:
      tags:
      - Article
      description: Retrive all published articles
      parameters:
      - name: page
        in: query
        description: current page number
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          example: 2
      - name: limit
        in: query
        description: maximum items to be returned
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          example: 10
      - name: sort_type
        in: query
        description: type of sort (asc or dsc)
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: dsc
          enum:
          - asc
          - dsc
      - name: sort_by
        in: query
        description: Sort key
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: updatedAt
      - name: search
        in: query
        description: Search term
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: title
      responses:
        "200":
          description: Return a list of articles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_1'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
    post:
      tags:
      - Article
      description: Create a new article
      operationId: createPost
      requestBody:
        description: To create a new article user must need to provide valid data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/articles_body'
      responses:
        "201":
          description: Successfully created a new article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_201_1'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_401'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
      security:
      - bearerAuth: []
components:
  schemas:
    Article:
      allOf:
      - required:
        - authorId
        - body
        - id
        - status
        - title
        type: object
        properties:
          id:
            type: integer
            format: int32
            example: 1
          authorId:
            type: integer
            format: int32
            example: 1
          title:
            type: string
            example: First Article
          body:
            type: string
            format: text
            example: The body of the first article
          cover:
            type: string
            format: url
            example: https://s3.aws.example.com/23nds
          status:
            type: string
            example: draft
            enum:
            - draft
            - published
      - $ref: '#/components/schemas/Timestamp'
    Timestamp:
      required:
      - createdAt
      - updatedAt
      type: object
      properties:
        createdAt:
          type: string
          format: datetime
        updatedAt:
          type: string
          format: datetime
    AuthorDTO:
      required:
      - id
      - name
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 1
        name:
          type: string
          example: A.B Raihan
    Pagination:
      required:
      - limit
      - page
      - totalItems
      - totalPage
      type: object
      properties:
        page:
          type: integer
          format: int32
          example: 2
        limit:
          type: integer
          format: int32
          example: 10
        next:
          type: integer
          format: int32
          example: 3
        prev:
          type: integer
          format: int32
          example: 1
        totalPage:
          type: integer
          format: int32
          example: 5
        totalItems:
          type: integer
          format: int32
          example: 50
    auth_signup_body:
      required:
      - email
      - name
      - password
      type: object
      properties:
        name:
          type: string
          example: Abdullah Alamin
        email:
          type: string
          format: email
          example: alamin@example.com
        password:
          type: string
          format: password
          example: PassWord123
    inline_response_201:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 201
        message:
          type: string
          example: Signup successful
        data:
          $ref: '#/components/schemas/inline_response_201_data'
        links:
          $ref: '#/components/schemas/inline_response_201_links'
    inline_response_400:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 400
        error:
          type: string
          example: Bad Request
        data:
          type: array
          items:
            $ref: '#/components/schemas/inline_response_400_data'
    inline_response_500:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 500
        error:
          type: string
          example: Internal Server Error
        message:
          type: string
          example: We are sorry for the inconvenience. Please try again later
    auth_signin_body:
      required:
      - email
      - password
      type: object
      properties:
        email:
          type: string
          format: email
          example: alamin@example.com
        password:
          type: string
          format: password
          example: PassWord123
    inline_response_200:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 200
        message:
          type: string
          example: Signin successful
        data:
          $ref: '#/components/schemas/inline_response_201_data'
        links:
          $ref: '#/components/schemas/inline_response_200_links'
    inline_response_200_1:
      type: object
      properties:
        data:
          type: array
          items:
            allOf:
            - required:
              - author
              - id
              - title
              type: object
              properties:
                id:
                  type: integer
                  format: int32
                  example: 1
                title:
                  type: string
                  example: first article
                cover:
                  type: string
                  format: url
                  example: https://s3.aws.com/myfirstblog/124.jpg
                author:
                  $ref: '#/components/schemas/AuthorDTO'
                link:
                  type: string
                  format: url
                  example: /articles/1
            - $ref: '#/components/schemas/Timestamp'
        pagination:
          $ref: '#/components/schemas/Pagination'
        links:
          $ref: '#/components/schemas/inline_response_200_1_links'
    articles_body:
      required:
      - body
      - title
      type: object
      properties:
        title:
          type: string
          example: First article
        body:
          type: string
          format: text
          example: Body of the first article
        cover:
          type: string
          format: url
          example: https://s3.aws.example.com/23nds
        status:
          type: string
          example: draft
          enum:
          - draft
          - published
    inline_response_201_1:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 201
        message:
          type: string
          example: Article created successfully
        data:
          $ref: '#/components/schemas/Article'
        links:
          $ref: '#/components/schemas/inline_response_201_1_links'
    inline_response_401:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 401
        error:
          type: string
          example: Unauthorized
        message:
          type: string
          example: You don't have the right permissions
    inline_response_201_data:
      type: object
      properties:
        access_token:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
    inline_response_201_links:
      type: object
      properties:
        self:
          type: string
          example: /auth/signup
        signin:
          type: string
          example: /auth/signin
    inline_response_400_data:
      type: object
      properties:
        field:
          type: string
          example: email
        message:
          type: string
          example: Invalid email
        in:
          type: string
          example: body
          enum:
          - query
          - body
    inline_response_200_links:
      type: object
      properties:
        self:
          type: string
          example: /auth/signin
    inline_response_200_1_links:
      type: object
      properties:
        self:
          type: string
          format: url
          example: /articles?page=2&limit=10
        next:
          type: string
          format: url
          example: /articles?page=3&limit=10
        prev:
          type: string
          format: url
          example: /articles?page=1&limit=10
    inline_response_201_1_links:
      type: object
      properties:
        self:
          type: string
          format: url
          example: /articles/1
        author:
          type: string
          format: url
          example: /articles/1/author
        comments:
          type: string
          format: url
          example: /articles/1/comments
  responses:
    "500":
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_response_500'
    "400":
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_response_400'
    "401":
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_response_401'
  parameters:
    pageParam:
      name: page
      in: query
      description: current page number
      required: false
      style: form
      explode: true
      schema:
        type: integer
        format: int32
        example: 2
    limitParam:
      name: limit
      in: query
      description: maximum items to be returned
      required: false
      style: form
      explode: true
      schema:
        type: integer
        format: int32
        example: 10
    sortTypeParam:
      name: sort_type
      in: query
      description: type of sort (asc or dsc)
      required: false
      style: form
      explode: true
      schema:
        type: string
        example: dsc
        enum:
        - asc
        - dsc
    sortByParam:
      name: sort_by
      in: query
      description: Sort key
      required: false
      style: form
      explode: true
      schema:
        type: string
        example: updatedAt
    searchParam:
      name: search
      in: query
      description: Search term
      required: false
      style: form
      explode: true
      schema:
        type: string
        example: title
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT