rest/swagger3 project.yml

openapi: 3.0.1
info:
  title: Project API
  description: |
    Latihan Project API 
    
    - CRUD Project 
    - Platform Relationship 
    - Auth 
    - Membership & Ownership
    - Rights & Paging
  version: 5.0.0
servers:
- url: http://localhost:8080/api/v1
tags:
- name: projects
  description: everything project
- name: platforms
  description: everything platform
- name: users
  description: everything user
paths:
  /projects:
    get:
      tags:
      - projects
      summary: find all project
      description: return all project
      operationId: getProject
      parameters: 
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/sortQuery'
      responses:
        200:
          $ref: '#/components/responses/getArrayProject'
        401:
          $ref: '#/components/responses/UnauthorizedError'
      security: 
        - testAuth: []
    post:
      tags:
      - projects
      summary: Add new Project
      description: Add new Project
      operationId: addProject
      requestBody:
        $ref: '#/components/requestBodies/Project'
      responses:
        201:
          $ref: '#/components/responses/successAddProject'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        409:
          $ref: '#/components/responses/409'
        413:
          $ref: '#/components/responses/413'
      security: 
        - testAuth: []
  /projects/{projectId}:
    get:
      tags:
      - projects
      summary: find project by ID
      description: return project
      operationId: getProjectById
      parameters:
        - $ref: '#/components/parameters/projectPath'
      responses:
        200:
          $ref: '#/components/responses/getSingleProject'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
      security: 
        - testAuth: []
    put:
      tags:
      - projects
      summary: update existing project by ID
      description: update project
      operationId: updateProjectById
      parameters:
        - $ref: '#/components/parameters/projectPath'
      requestBody:
        $ref: '#/components/requestBodies/Project'
      responses:
        200:
          $ref: '#/components/responses/getSingleProject'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/403'
        409:
          $ref: '#/components/responses/409'
        413:
          $ref: '#/components/responses/413'
      security: 
        - testAuth: []
    delete:
      tags:
      - projects
      summary: Deletes a project 
      description: delete a project
      operationId: deleteProject
      parameters:
        - $ref: '#/components/parameters/projectPath'
      responses:
        200:
          description: successful operation
        205:
          description: Unable to delete. Data is used.
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/403'
      security: 
        - testAuth: []
  /projects/{projectId}/member:
    get:
      tags: 
      - projects
      summary: find all member by project
      description: return all member by project
      operationId: getMemberByProject
      parameters: 
        - $ref: '#/components/parameters/projectPath'
        - $ref: '#/components/parameters/roleQuery'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - name: sort
          in: query
          description: sort direction (default 'member_id, desc')
          schema:
            type: string
      responses:
        200:
          $ref: '#/components/responses/getArrayMember'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/UnauthorizedError'
      security:
      - testAuth: []
    post:
      tags:
      - projects
      summary: add project member
      description: add project member
      operationId: addProjectMember
      parameters: 
        - $ref: '#/components/parameters/projectPath'
      requestBody:
        $ref: '#/components/requestBodies/ProjectMember'
      responses:
        201:
          $ref: '#/components/responses/successAddMember'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        409:
          $ref: '#/components/responses/409'
      security: 
        - testAuth: []
  /projects/member/{memberId}:
    get:
      tags: 
      - projects
      summary: find member by ID
      description: return member by ID
      operationId: getMemberProject
      parameters: 
        - $ref: '#/components/parameters/memberPath'
      responses:
        200:
          $ref: '#/components/responses/getSingleMember'
        401:
          $ref: '#/components/responses/UnauthorizedError'
      security: 
      - testAuth: []
    delete:
      tags: 
      - projects
      summary: delete project member
      description: delete project member 
      operationId: deleteProjectMember
      parameters: 
        - $ref: '#/components/parameters/memberPath'
      responses:
        200:
          description: successful operation
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
      security: 
        - testAuth: []
  /platforms:
    get:
      tags: 
      - platforms
      summary: find all platform of a project
      description: return all platform of a project
      operationId: getPlatformByProjectId
      parameters: 
        - $ref: '#/components/parameters/projectQuery'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/sortQuery'
      responses:
        200:
          $ref: '#/components/responses/getArrayPlatform'
        401:
          $ref: '#/components/responses/UnauthorizedError'
      security: 
        - testAuth: []
    post:
      tags: 
      - platforms
      summary: Add new platform for a project
      description: add new platform for a project
      operationId: addPlatformByProjectId
      requestBody:
        $ref: '#/components/requestBodies/Platform'
      responses:
        201:
          $ref: '#/components/responses/successAddPlatform'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        409:
          $ref: '#/components/responses/409'
        413:
          $ref: '#/components/responses/413'
      security: 
        - testAuth: []
  /platforms/{platformId}:
    get:
      tags: 
      - platforms
      summary: find platform by ID
      description: return platform by ID
      operationId: getPlatformById
      parameters: 
        - $ref: '#/components/parameters/platformPath'
      responses:
        200:
          $ref: '#/components/responses/getSinglePlatform'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/404'
      security: 
        - testAuth: []
    put:
      tags: 
      - platforms
      summary: update existing platform by ID
      description: update platform
      operationId: updatePlatformById
      parameters: 
        - $ref: '#/components/parameters/platformPath'
      requestBody:
        $ref: '#/components/requestBodies/Platform'
      responses:
        200:
          $ref: '#/components/responses/getSinglePlatform'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        409:
          $ref: '#/components/responses/409'
        413:
          $ref: '#/components/responses/413'
      security: 
        - testAuth: []
    delete:
      tags: 
      - platforms
      summary: deletes a platform by ID
      description: delete a platform by ID
      operationId: deletePlatformById
      parameters: 
        - $ref: '#/components/parameters/platformPath'
      responses:
        200:
          description: successful operation
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
      security: 
        - testAuth: []
  /users:
    get:
      tags: 
      - users
      summary: find all user
      description: return all user
      operationId: getUser
      parameters: 
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/sortQuery'
      responses:
        200:
          $ref: '#/components/responses/getArrayUser'
        401:
          $ref: '#/components/responses/UnauthorizedError'
      security: 
        - testAuth: []
    post:
      tags: 
      - users
      summary: add user
      description: add new user
      operationId: AddUser
      requestBody:
        $ref: '#/components/requestBodies/User'
      responses:
        201:
          $ref: '#/components/responses/successAddUser'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        409:
          $ref: '#/components/responses/409'
        413:  
          $ref: '#/components/responses/413'
      security: 
        - testAuth: []
  /users/{userId}:
    get:
      tags: 
      - users
      summary: find user by userId
      description: return user by userId
      operationId: getUserById
      parameters: 
        - $ref: '#/components/parameters/UserPath'
      responses:
        200:
          $ref: '#/components/responses/getSingleUser'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/404'
      security: 
        - testAuth: []
    put:
      tags: 
      - users
      summary:  update existing user except password
      description: update user
      operationId: updateUserById
      parameters: 
        - $ref: '#/components/parameters/UserPath'
      requestBody:
        description: User object
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: abi
                name:
                  type: string
                  example: abidzar
      responses:
        200:
          $ref: '#/components/responses/getSingleUser'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/404'
        409:
          $ref: '#/components/responses/409'
        413:
          $ref: '#/components/responses/413'
      security: 
        - testAuth: []
    delete:
      tags: 
      - users
      summary: deletes a user by ID
      description: delete a user by ID
      operationId: deleteUserById
      parameters: 
        - $ref: '#/components/parameters/UserPath'
      responses:
        200:
          description: successful operation
        205:
          description: Unable to delete. Data is used.
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/404'
      security: 
        - testAuth: []
  /users/{userId}/password:
    put:
      tags: 
      - users
      summary:  change password
      description: update user password
      operationId: updatePassword
      parameters: 
        - $ref: '#/components/parameters/UserPath'
      requestBody:
        description: User object
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                oldPassword:
                  type: string
                  example: abi123
                newPassword:
                  type: string
                  example: abi456
      responses:
        200:
          $ref: '#/components/responses/getSingleUser'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          description: wrong old password
        404:
          $ref: '#/components/responses/404'
      security: 
        - testAuth: []
components:
  schemas:
    Project:
      required:
        - id
        - name
        - owner
      type: object
      properties:
        id:
          type: integer
          uniqueItems: true
          example: 2
        name:
          type: string
          uniqueItems: true
          maximum: 100
          example: PI
        description:
          type: string
          maximum: 255
          example: PropInspector
        owner:
          $ref: '#/components/schemas/User'
    Platform:
      type: object
      required: 
        - id
        - name
      properties:
        id:
          type: integer
          uniqueItems: true
          example: 3
        name:
          type: string
          uniqueItems: true
          maximum: 100
          example: mobile
        project_id:
          $ref: '#/components/schemas/Project'
    User:
      type: object
      required:
        - id
        - username
        - password
        - name
      properties:
        id:
          type: integer
          uniqueItems: true
          example: 4
        username:
          type: string
          uniqueItems: true
          maximum: 100
          example: abi
        password:
          type: string
          maximum: 100
          example: abi123
        name:
          type: string
          maximum: 255
          example: abidzar
    project_member:
      type: object
      properties:
        id:
          type: integer
          uniqueItems: true
        project:
          $ref: '#/components/schemas/Project'
        user:
          $ref: '#/components/schemas/User'
        role:
          type: number
          enum: [0,1,2]
          description: role = 0.QC, 1. Programmer, 2.Admin
      required: 
        - id
        - project
        - user
        - role
    PaginatedResult:
      type: object
      properties:
        totalPage: { type: number, example: 2 }
        currentPage: { type: number, example: 0 }
        totalRecord: { type: number, example: 4 }
        results: { type: array, items: {} }
  parameters:
    projectPath:
      name: projectId
      in: path
      description: Project ID
      required: true
      schema:
        type: integer
    platformPath:
      name: platformId
      in: path
      description: Platform ID
      required: true
      schema:
        type: integer
    UserPath:
      name: userId
      in: path
      description: User ID
      required: true
      schema:
        type: integer
    projectQuery:
      name: project
      in: query
      description: Project ID
      schema:
        type: integer
    memberPath:
      name: memberId
      in: path
      description: Project Member ID
      required: true
      schema:
        type: integer
    limit:
      name: limit
      in: query
      description: Number of records to return (default 3)
      schema:
        type: number
    page:
      name: page
      in: query
      description: Number of page to return (default 0)
      schema:
        type: number
    roleQuery:
      name: role
      in: query
      description: filter role
      schema:
        type: string
    sortQuery:
      name: sort
      in: query
      description: sort direction (default 'id, desc')
      schema:
        type: string
  responses:
    getArrayProject:
      description: successful operation
      content:
        application/json:
          schema:
            type: object
            allOf:
              - $ref: '#/components/schemas/PaginatedResult'
              - type: object
                properties:
                  results:
                    type: array
                    items:
                      properties:
                        id: 
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: TM
                        description:
                          type: string
                          example: TelMesengger
                        owner:
                          properties:
                            id:
                              type: integer
                              example: 1
                            username:
                              type: string
                              example: abi
                            name:
                              type: string
                              example: abidzar
    getSingleProject:
      description: successful operation
      content:
        application/json:
          schema:
            properties:
              id: 
                type: integer
                example: 1
              name:
                type: string
                example: TM
              description:
                type: string
                example: TelMesengger
              owner:
                properties:
                  id:
                    type: integer
                    example: 1
                  username:
                    type: string
                    example: abi
                  name:
                    type: string
                    example: abidzar
    successAddProject:
      description: record successfully added
      content:
        application/json:
          schema:
              properties:
                id: 
                  type: integer
                  example: 1
                name:
                  type: string
                  example: TM
                description:
                  type: string
                  example: TelMesengger
                owner:
                  properties:
                    id:
                      type: integer
                      example: 1
                    username:
                      type: string
                      example: abi
                    name:
                      type: string
                      example: abidzar
    successAddMember:
      description: record successfully added
      content:
        application/json:
          schema:
            properties:
              id:
                type: integer
                example: 1
              project:
                example: TelMessenger
              user:
                example: abidzar
              role:
                type: string
                example: QC
    getArrayPlatform:
      description: successful operation
      content:
        application/json:
          schema:
            type: object
            allOf:
              - $ref: '#/components/schemas/PaginatedResult'
              - type: object
                properties:
                  results:
                    type: array
                    items: 
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: mobile
                        project_id:
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: TM
                            description:
                              type: string
                              example: TelMessenger
                            owner:
                              properties:
                                id:
                                  type: integer
                                  example: 1
                                username:
                                  type: string
                                  example: abi
                                name:
                                  type: string
                                  example: abidzar            
    successAddPlatform:
      description: record successfully added
      content:
        application/json:
          schema:
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: mobile
              project_id:
                properties:
                  id:
                    type: integer
                    example: 1
                  name:
                    type: string
                    example: TM
                  description:
                    type: string
                    example: TelMessenger
                  owner:
                    properties:
                      id:
                        type: integer
                        example: 1
                      username:
                        type: string
                        example: abi
                      name:
                        type: string
                        example: abidzar
    getSinglePlatform:
      description: successful operation
      content:
        application/json:
          schema:
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: mobile
              project_id:
                properties:
                  id:
                    type: integer
                    example: 1
                  name:
                    type: string
                    example: TM
                  description:
                    type: string
                    example: TelMessenger
                  owner:
                    properties:
                      id:
                        type: integer
                        example: 1
                      username:
                        type: string
                        example: abi
                      name:
                        type: string
                        example: abidzar
    getArrayUser:
      description: successful operation
      content:
        application/json:
          schema:
            type: object
            allOf:
              - $ref: '#/components/schemas/PaginatedResult'
              - type: object
                properties:
                  results:
                    type: array
                    items: 
                      properties:
                        id:
                          type: integer
                          example: 1
                        username:
                          type: string
                          example: abi
                        name:
                          type: string
                          example: abidzar
    successAddUser:
      description: record successfully added
      content:
        application/json:
          schema:
              properties:
                id:
                  type: integer
                  example: 1
                username:
                  type: string
                  example: abi
                name:
                  type: string
                  example: abidzar
    getSingleUser:
      description: successful operation
      content:
        application/json:
          schema:
              properties:
                id:
                  type: integer
                  example: 1
                username:
                  type: string
                  example: abi
                name:
                  type: string
                  example: abidzar
    getSingleMember:
      description: successful operation
      content:
        application/json:
          schema:
            properties:
              id:
                example: 1
              project:
                example: TelMessenger
              user:
                example: abidzar
              role:
                example: QC
    getArrayMember:
      description: successful operation
      content:
        application/json:
          schema:
            type: object
            allOf:
              - $ref: '#/components/schemas/PaginatedResult'
              - type: object
                properties:
                  results:
                    type: array
                    items:
                      properties:
                        id:
                          example: 1
                        project:
                          example: TelMessenger
                        user:
                          example: abidzar
                        role:
                          example: QC
    400:
      description: invalid data
    403:
      description: do not have rights
    UnauthorizedError:
      description: Authentication information is missing or invalid
    404:
      description: not found
    409:
      description: duplicate data
    413:
      description: content too large
  requestBodies:
    Project:
      description: Project object 
      required: true
      content: 
        application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: TM
                description:
                  type: string
                  example: TelMesengger
    ProjectMember:
      description: project member object
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              user_id:
                type: integer
                example: 1
              role:
                type: string
                example: qc
    Platform:
      description: Platform object
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                example: web
              project_name:
                type: string
                example: TM
    User:
      description: User object
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              username:
                type: string
                example: abi
              password:
                type: string
                example: abi123
              name:
                type: string
                example: abidzar
  securitySchemes:
    testAuth:
      type: http
      scheme: basic
      description: use `user`/`password` to login