API tools faq
paste
Advertisement
Guest User

Untitled

a guest
Sep 25th, 2018
115
0
Never
Add comment
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
YAML 36.14 KB | None | 0 0
raw download clone embed print report
  1. openapi: 3.0.0
  2. info:
  3.   title: TusionAPI
  4.   description: |
  5.    Tusion rest server API
  6.  
  7.     \[SwaggerUI\] $$ref in examples is a bug and should be ignored!
  8.  
  9.   version: 1.0.0
  10.   contact:
  11.     email: "konstantin@tusion.xyz"
  12. servers:
  13.   - url: http://api.tusion.xyz/v1
  14.     description: Production rest server
  15.   - url: 178.128.32.99:8080/v1
  16.     description: Test rest server
  17.  
  18. tags:
  19.   - name: Profile
  20.     description: Current user's profile related endpoints
  21.   - name: Departments
  22.     description: Departments related endpoints
  23.   - name: Employees
  24.     description: Employees related endpoints
  25.   - name: Other
  26.     description: Miscellaneous endpoints
  27.   - name: Rate
  28.     description: Rate endpoints
  29.  
  30.  
  31. components:
  32.   securitySchemes:
  33.     ApiKeyAuth:
  34.       type: apiKey
  35.       in: header
  36.       name: Authorization
  37.   schemas:
  38.  
  39.     Rate:
  40.       type: object
  41.       properties:
  42.         rate: { type: integer }
  43.         date: { type: string }
  44.         goalID: { type: integer }
  45.       example:
  46.         rate: 1
  47.         date: "2018-02-02"
  48.         goalID: 1
  49.        
  50.     Organisation:
  51.       type: object
  52.       properties:
  53.         name: { type: string }
  54.         logoUrl: { type: string, format: url }
  55.       example:
  56.         name: Tusion
  57.         logoUrl: https://tusion.xyz/assets/logo
  58.      
  59.     Department:
  60.       type: object
  61.       properties:
  62.         id: { type: integer }
  63.         title: { type: string }
  64.         isMain: { type: boolean }
  65.         statistics:
  66.           type: object
  67.           properties:
  68.             tpi: { type: number }
  69.             avgRating: { type: number }
  70.       example: { $ref: '#/components/examples/Department_Tusion/value' }
  71.  
  72.     Employee:
  73.       type: object
  74.       properties:
  75.         id: { type: integer, example: 1 }
  76.         name: { type: string, example: John Doe }
  77.         email: { type: string, format: email, example: jh@tusion.xyz }
  78.         photoUrl: { type: string, format: uri, example: https://tusion.xyz/jhPhoto }
  79.         position: { type: string, example: Golang developer }
  80.         isAdmin: { type: boolean }
  81.         timezone: { type: string, format: TZ, example: UTC }
  82.         goal:
  83.           type: object
  84.           properties:
  85.             name: { type: string }
  86.             type:
  87.               type: string
  88.               enum: [concentration, relaxation]
  89.         statistics: { $ref: '#/components/schemas/EmployeeStatistics' }
  90.  
  91.     EmployeeStatistics:
  92.       type: object
  93.       properties:
  94.         tpi: { type: number }
  95.         data:
  96.           type: array
  97.           items:
  98.             type: object
  99.             properties:
  100.               date: { type: string, format: date }
  101.               adminRating: { type: integer }
  102.               selfRating: { type: integer }
  103.               relaxation: { $ref: '#/components/schemas/IntTusesStatistics' }
  104.               concentration: { $ref: '#/components/schemas/IntTusesStatistics' }
  105.               duration: { $ref: '#/components/schemas/IntTusesStatistics' }
  106.       example: { $ref: '#/components/examples/EmployeeStatistics/value' }
  107.  
  108.     IntTusesStatistics:
  109.       type: object
  110.       properties:
  111.         spinner: { type: integer }
  112.         way: { type: integer }
  113.         reaperoid3000: { type: integer }
  114.         jumper: { type: integer }
  115.         pushazier: { type: integer }
  116.         modernSnake: { type: integer }
  117.         cleanTheDay: { type: integer }
  118.        
  119.     DashboardContent:
  120.       type: object
  121.       properties:
  122.         department: { $ref: '#/components/schemas/Department' }
  123.         otherSubordinates:
  124.           type: array
  125.           items: { $ref: '#/components/schemas/Employee' }
  126.       example:
  127.         department:
  128.           id: 1
  129.           title: Tusion
  130.           isMain: false
  131.           staff:
  132.             - $ref: '#/components/examples/Employee_Andrey/value'
  133.             - $ref: '#/components/examples/Employee_Konstantin/value'
  134.           statistics:
  135.             tpi: 45.2
  136.             avgRating: 4.5
  137.         otherSubordinates:
  138.           - $ref: '#/components/examples/Employee_John1/value'
  139.           - $ref: '#/components/examples/Employee_John2/value'
  140.  
  141.     DepartmentsHierarchyItem:
  142.       type: object
  143.       properties:
  144.         id: { type: integer }
  145.         name: { type: string }
  146.         subdepartments:
  147.           type: array
  148.           items: { $ref: '#/components/schemas/DepartmentsHierarchyItem' }
  149.       example:
  150.         id: 1
  151.         name: Tusion
  152.         subdepartments:
  153.           - id: 2
  154.             name: Development Department
  155.             subdepartments:
  156.               - id: 5
  157.                 name: Mobile Development Department
  158.                 subdepartments: []
  159.               - id: 6
  160.                 name: Backoffice Development Department
  161.                 subdepartments: []
  162.           - id: 3
  163.             name: HR Department
  164.             subdepartments: []
  165.           - id: 4
  166.             name: PR Department
  167.             subdepartments: []
  168.  
  169.     Error:
  170.       type: object
  171.       properties:
  172.         code: { type: integer, minimum: 100, maximum: 999 }
  173.         message: { type: string }
  174.  
  175.   examples:
  176.     Department_Tusion:
  177.       summary: Main department example
  178.       value:
  179.         id: 1
  180.         title: Tusion
  181.         isMain: true
  182.         statistics:
  183.           tpi: 45.2
  184.           avgRating: 4.5
  185.    
  186.     Employee_Andrey:
  187.       summary: Employee example — Andrey
  188.       value:
  189.         id: 1
  190.         name: Andrey Khapsasov
  191.         email: ak@tusion.xyz
  192.         photoUrl: https://staff.tusion.xyz/ak/photo
  193.         position: CEO, Alcoholic
  194.         timezone: Europe/Moscow
  195.         goal:
  196.           name: Find a girlfriend
  197.           type: concentration
  198.         statistics: { $ref: '#/components/examples/EmployeeStatistics/value'}
  199.    
  200.     Employee_Konstantin:
  201.       summary: Employee example — Konstantin
  202.       value:
  203.         id: 2
  204.         name: Konstantin Mazunin
  205.         email: km@tusion.xyz
  206.         photoUrl: https://staff.tusion.xyz/km/photo
  207.         position: CTO, Anime fan
  208.         timezone: Europe/Moscow
  209.         goal:
  210.           name: Buy a Bentley
  211.           type: concentration
  212.         statistics: { $ref: '#/components/examples/EmployeeStatistics/value' }
  213.  
  214.     Employee_John1:
  215.       summary: Employee example — John 1
  216.       value:
  217.         id: 10
  218.         name: John Doe 1
  219.         email: jh@tusion.xyz
  220.         photoUrl: https://staff.tusion.xyz/jh1/photo
  221.         position: Jumper 1
  222.         timezone: Australia/Sydney
  223.         goal:
  224.           name: Be a good jumper 2
  225.           type: relaxation
  226.         statistics: { $ref: '#/components/examples/EmployeeStatistics/value' }
  227.  
  228.     Employee_John2:
  229.       summary: Employee example — John 2
  230.       value:
  231.         id: 10
  232.         name: John Doe 2
  233.         email: jh@tusion.xyz
  234.         photoUrl: https://staff.tusion.xyz/jh2/photo
  235.         position: Jumper 2
  236.         timezone: Australia/Sydney
  237.         goal:
  238.           name: Be a good jumper 2
  239.           type: relaxation
  240.         statistics: { $ref: '#/components/examples/EmployeeStatistics/value' }
  241.  
  242.     EmployeeStatistics:
  243.       summary: Employee statistics example
  244.       value:
  245.         tpi: 45.2
  246.         data:
  247.           - date: '2018-07-01T21:00:00Z'
  248.             adminRatig: 4
  249.             selfRating: 6
  250.             relaxation:
  251.               spinner: 9
  252.               way: 1
  253.               reaperoid3000: 0
  254.               jumper: 3
  255.               pushazier: 4
  256.               modernSnake: 1
  257.               cleanTheDay: 3
  258.             concentration:
  259.               spinner: 9
  260.               way: 1
  261.               reaperoid3000: 0
  262.               jumper: 3
  263.               pushazier: 4
  264.               modernSnake: 1
  265.               cleanTheDay: 3
  266.             duration:
  267.               spinner: 5
  268.               way: 1
  269.               reaperoid3000: 0
  270.               jumper: 3
  271.               pushazier: 4
  272.               modernSnake: 1
  273.               cleanTheDay: 3
  274.           - date: '2018-07-02T21:00:00Z'
  275.             adminRatig: 3
  276.             selfRating: 5
  277.             relaxation:
  278.               spinner: 9
  279.               way: 1
  280.               reaperoid3000: 0
  281.               jumper: 3
  282.               pushazier: 4
  283.               modernSnake: 1
  284.               cleanTheDay: 3
  285.             concentration:
  286.               spinner: 5
  287.               way: 1
  288.               reaperoid3000: 0
  289.               jumper: 3
  290.               pushazier: 4
  291.               modernSnake: 1
  292.               cleanTheDay: 3
  293.             duration:
  294.               spinner: 5
  295.               way: 1
  296.               reaperoid3000: 0
  297.               jumper: 3
  298.               pushazier: 4
  299.               modernSnake: 1
  300.               cleanTheDay: 2
  301.                
  302.   parameters:
  303.     employeeFields:
  304.       name: fields
  305.       description: |
  306.        Array of expected employee atttribute names
  307.        
  308.         Style — form, no explode
  309.        
  310.         **Example**
  311.  
  312.         `[ id, name, position, goal ] -> ?fields=id,name,position,goal`
  313.       in: query
  314.       required: false
  315.       style: form
  316.       explode: false
  317.       schema:
  318.         type: array
  319.         items: { type: string }
  320.         default: [ id, name, email, photoUrl, position, isAdmin, timezone, goal, statistics ]
  321.         example: [ id, name, position, goal ]
  322.  
  323.     departmentFields:
  324.       name: fields
  325.       description: |
  326.        Array of expected department atttribute names
  327.        
  328.         Style — form, no explode
  329.        
  330.         **Example**
  331.  
  332.         `[ id, title, isMain ] -> ?fields=id,title,isMain`
  333.       in: query
  334.       required: false
  335.       style: form
  336.       explode: false
  337.       schema:
  338.         type: array
  339.         items: { type: string }
  340.         default: [ id, title, isMain, statistics ]
  341.         example: [ id, title, statistics ]
  342.  
  343.     organisationFields:
  344.       name: fields
  345.       description: |
  346.        Array of expected organisation atttribute names
  347.        
  348.         Style — form, no explode
  349.        
  350.         **Example**
  351.  
  352.         `[ title, logoUrl ] -> ?fields=title,logoUrl`
  353.       in: query
  354.       required: false
  355.       style: form
  356.       explode: false
  357.       schema:
  358.         type: array
  359.         items: { type: string }
  360.         default: [ title, logoUrl ]
  361.         example: [ title, logoUrl ]
  362.  
  363.     departmentId:
  364.       name: depId
  365.       in: path
  366.       description: Department's id
  367.       required: true
  368.       schema: { type: integer, example: 1 }
  369.  
  370.     employeeId:
  371.       name: employeeId
  372.       in: path
  373.       description: Employee's id
  374.       required: true
  375.       schema: { type: integer, example: 1 }
  376.      
  377.     start:
  378.       name: start
  379.       description: |
  380.        Start date for statistics calculation (such as average department rating for last week)
  381.  
  382.         Format — ISO date and time in UTC timezone
  383.  
  384.         **Examples**: `?start=2018-07-01T21:00:00Z` — start of July 2nd in Europe/Moscow
  385.       in: query
  386.       required: false
  387.       schema:
  388.         type: string
  389.         format: date
  390.         default: \<utc time of current month start in users's timezone\>
  391.         example: '2018-07-01T21:00:00Z'
  392.    
  393.     end:
  394.       name: end
  395.       in: query
  396.       description: |
  397.        End date for statistics calculation (such as average department rating for last week)
  398.  
  399.         Format — ISO date in UTC timezone
  400.  
  401.         **Example**: `?end=2018-07-04T21:00:00Z` — start of July 5th in Europe/Moscow
  402.       required: false
  403.       schema:
  404.         type: string
  405.         format: date
  406.         default: \<utc time of current day start in users's timezone\>
  407.         example: '2018-07-04T21:00:00Z'
  408.  
  409.   responses:
  410.    # 1xx
  411.     UserIsUnauthenticated:
  412.       description: |
  413.        User is unauthenticated
  414.  
  415.         Possible cases:
  416.         * Access token is not supplied
  417.         * Access token is invalid
  418.         * Access token has expired
  419.       content:
  420.         application/json:
  421.           schema:
  422.             type: object
  423.             properties:
  424.               code: { type: integer, enum: [ 101 ] }
  425.               message: { type: string, enum: [ 'User is unauthenticated' ] }
  426.  
  427.     # 2xx
  428.     NotAdminAccessForbidden:
  429.       description: |
  430.        Access forbidden
  431.  
  432.         Possible reasons:
  433.         * Current user in not admin
  434.       content:
  435.         application/json:
  436.           schema:
  437.             type: object
  438.             properties:
  439.               code: { type: integer, enum: [ 201 ] }
  440.               message: { type: string, enum: [ 'Access forbidden: you are not and admin' ] }
  441.  
  442.     NotAdminOrDepartmentAccessForbidden:
  443.       description: |
  444.        Access forbidden
  445.  
  446.         Possible reasons:
  447.         * Current user is not admin
  448.         * Neither current user is a member of specified department nor
  449.           specified department is a direct or indirect subdepartment of
  450.           the department current user is a member of
  451.       content:
  452.         application/json:
  453.           schema:
  454.             type: object
  455.             properties:
  456.               code: { type: integer, enum: [ 201, 202 ] }
  457.               message: { type: string, enum: [
  458.                 'Access forbidden: you are not an admin',
  459.                 'Access forbidden: you don''t have control over specified department'
  460.               ] }
  461.  
  462.     NotAdminOrEmployeeAccessForbidden:
  463.       description: |
  464.        Access forbidden
  465.  
  466.         Possible reasons:
  467.         * Current user is not admin
  468.         * Specified employee is not direct or indirect subordinate of
  469.           current user
  470.       content:
  471.         application/json:
  472.           schema:
  473.             type: object
  474.             properties:
  475.               code: { type: integer, enum: [ 201, 203 ] }
  476.               message: { type: string, enum: [
  477.                 'Access forbidden: you are not an admin',
  478.                 'Access forbidden: you don''t have control over specified employee'
  479.               ] }
  480.  
  481.     NotAdminOrEmployeeOrDepartmentAccessForbidden:
  482.       description: |
  483.        Access forbidden
  484.  
  485.         Possible reasons:
  486.         * Current user is not admin
  487.         * Neither current user is a member of specified department nor
  488.           specified department is a direct or indirect subdepartment of
  489.           the department current user is a member of
  490.         * Specified employee is not direct or indirect subordinate of
  491.           current user
  492.       content:
  493.         application/json:
  494.           schema:
  495.             type: object
  496.             properties:
  497.               code: { type: integer, enum: [ 201, 202, 203 ] }
  498.               message: { type: string, enum: [
  499.                 'Access forbidden: you are not an admin',
  500.                 'Access forbidden: you don''t have control over specified department',
  501.                 'Access forbidden: you don''t have control over specified employee'
  502.               ] }
  503.  
  504.     AlreadyAdmin:
  505.       description: User already admin of department
  506.       content:
  507.         application/json:
  508.           schema:
  509.             type: object
  510.             properties:
  511.               code: { type: integer, enum: [ 211 ] }
  512.               message: { type: string, enum: [
  513.                 "This user is already admin: user can not be admin of more then one department"
  514.              ] }
  515.    
  516.    NoActiveGoalOrAlreadyRated:
  517.      description: |
  518.        Unposible to rate.
  519.        Possible reasons:
  520.          * User has no active goal, assigned by admin of department. Code = 212
  521.          * User has already rated himself at this day. Code = 213
  522.      content:
  523.        application/json:
  524.          schema:
  525.            type: object
  526.            properties:
  527.              code: { type: integer, enum: [212, 213] }
  528.              message: { type: string, enum: [
  529.                  "No active goal for user",
  530.                  "User has already rated at this date"
  531.                ] }
  532.              
  533.  
  534.    # 3xx
  535.    DepartmentNotFound:
  536.      description: Department with specified id wasn't found
  537.      content:
  538.        application/json:
  539.          schema:
  540.            type: object
  541.            properties:
  542.              code: { type: integer, enum: [ 301 ] }
  543.              message: { type: string, enum: [ 'Department wasn''t found' ] }
  544.  
  545.    EmployeeNotFound:
  546.      description: Employee with specified id wasn't found
  547.      content:
  548.        application/json:
  549.          schema:
  550.            type: object
  551.            properties:
  552.              code: { type: integer, enum: [ 302 ] }
  553.              message: { type: string, enum: [ 'Employee wasn''t found' ] }
  554.    
  555.    RateNotFound:
  556.      description: Rate for specified date not found
  557.      content:
  558.        application/json:
  559.          schema:
  560.            type: object
  561.            properties:
  562.              code: { type: integer, enum: [ 303 ] }
  563.              message: { type: string, enum: [
  564.                'No rate for required date'
  565.              ] }
  566.  
  567.  
  568.    BadJsonResponse:
  569.      description: Bad Request
  570.    ForbiddenAccessError:
  571.      description: Forbidden
  572.    LoginResponse:
  573.      description: OK
  574.      content:
  575.        application/json:
  576.          schema:
  577.            type: object
  578.            properties:
  579.              access_token:
  580.                type: string
  581.              refresh_token:
  582.                type: string
  583.              expires_in:
  584.                type: integer
  585.  
  586. paths:
  587.  /my_profile:
  588.    get:
  589.      tags:
  590.        - Profile
  591.      summary: Get current user's profile info
  592.      security:
  593.        - ApiKeyAuth: []
  594.      parameters:
  595.        - $ref: '#/components/parameters/employeeFields'
  596.        - $ref: '#/components/parameters/start'
  597.        - $ref: '#/components/parameters/end'
  598.      responses:
  599.        200:
  600.          description: Information fetched successfully
  601.          content: { application/json: { schema: { $ref: '#/components/schemas/Employee' } } }
  602.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  603.    patch:
  604.      tags:
  605.        - Profile
  606.      summary: Update current user's profile
  607.      security:
  608.        - ApiKeyAuth: []
  609.      requestBody:
  610.        description: |
  611.          Profile patch document in JSON merge patch format
  612.  
  613.          Properties available for update:
  614.          * name
  615.          * photoUrl
  616.        content:
  617.          application/json:
  618.            schema:
  619.              type: object
  620.              properties:
  621.                name: { type: string }
  622.                photoUrl: { type: string, format: url }
  623.      responses:
  624.        200:
  625.          description: Profile updated, response contains object width updated profile properties
  626.          content:
  627.            application/json:
  628.              schema:
  629.                type: object
  630.                properties:
  631.                  name: { type: string }
  632.                  photoUrl: { title: string, format: url }
  633.  
  634.  
  635.  /my_profile/organistation:
  636.    get:
  637.      tags:
  638.        - Profile
  639.      summary: Get current user's organistation info
  640.      security:
  641.        - ApiKeyAuth: []
  642.      parameters:
  643.        - $ref: '#/components/parameters/organisationFields'
  644.      responses:
  645.        200:
  646.          description: Information fetched successfully
  647.          content: { application/json: { schema: { $ref: '#/components/schemas/Organisation' } } }
  648.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  649.  
  650.  /my_profile/department:
  651.    get:
  652.      tags:
  653.        - Profile
  654.        - Departments
  655.      summary: Get current user's department info
  656.      security:
  657.        - ApiKeyAuth: []
  658.      parameters:
  659.        - $ref: '#/components/parameters/departmentFields'
  660.        - $ref: '#/components/parameters/start'
  661.        - $ref: '#/components/parameters/end'
  662.      responses:
  663.        200:
  664.          description: OK
  665.          content: { application/json: { schema: { $ref: '#/components/schemas/Department' } } }
  666.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  667.  
  668.  # ** Departments specific endpoints ** #
  669.  /departments/{depId}:
  670.    get:
  671.      tags:
  672.        - Departments
  673.      summary: Get info about department with specified id
  674.      security:
  675.        - ApiKeyAuth: []
  676.      parameters:
  677.        - $ref: '#/components/parameters/departmentId'
  678.        - $ref: '#/components/parameters/departmentFields'
  679.        - $ref: '#/components/parameters/start'
  680.        - $ref: '#/components/parameters/end'
  681.      responses:
  682.        200:
  683.          description: Information fetched successfully
  684.          content: { application/json: { schema: { $ref: '#/components/schemas/Department' } } }
  685.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  686.        403: { $ref: '#/components/responses/NotAdminOrDepartmentAccessForbidden' }
  687.        404: { $ref: '#/components/responses/DepartmentNotFound' }
  688.    patch:
  689.      tags:
  690.        - Departments
  691.      summary: Update info about department width specified id
  692.      security:
  693.        - ApiKeyAuth: []
  694.      parameters:
  695.        - $ref: '#/components/parameters/departmentId'
  696.      requestBody:
  697.        description: |
  698.          Department patch document in JSON merge patch format
  699.  
  700.          Properties available for update:
  701.          * title
  702.        required: true
  703.        content:
  704.          application/json:
  705.            schema:
  706.              type: object
  707.              properties:
  708.                title: { type: string }
  709.      responses:
  710.        200:
  711.          description: Department info updated, response contains object width updated properties
  712.          content:
  713.            application/json:
  714.              schema:
  715.                type: object
  716.                properties:
  717.                  title: { type: string }
  718.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  719.        403: { $ref: '#/components/responses/NotAdminOrDepartmentAccessForbidden' }
  720.        404: { $ref: '#/components/responses/DepartmentNotFound' }
  721.    delete:
  722.      tags:
  723.        - Departments
  724.      summary: Delete department with specified id
  725.      security:
  726.        - ApiKeyAuth: []
  727.      parameters:
  728.        - $ref: '#/components/parameters/departmentId'
  729.      responses:
  730.        204:
  731.          description: Department width specific id successfully deleted
  732.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  733.        403: { $ref: '#/components/responses/NotAdminOrDepartmentAccessForbidden' }
  734.        404: { $ref: '#/components/responses/DepartmentNotFound' }
  735.  
  736.  /departments/{depId}/subdepartments:
  737.    get:
  738.      tags:
  739.        - Departments
  740.      summary: Get subdepartments list of department with specified id
  741.      security:
  742.        - ApiKeyAuth: []
  743.      parameters:
  744.        - $ref: '#/components/parameters/departmentId'
  745.        - $ref: '#/components/parameters/departmentFields'
  746.        - $ref: '#/components/parameters/start'
  747.        - $ref: '#/components/parameters/end'
  748.      responses:
  749.        200:
  750.          description: Information fetched successfully
  751.          content:
  752.            application/json:
  753.              schema: { type: array, items: { $ref: '#/components/schemas/Department' } }
  754.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  755.        403: { $ref: '#/components/responses/NotAdminOrDepartmentAccessForbidden' }
  756.        404: { $ref: '#/components/responses/DepartmentNotFound' }
  757.    post:
  758.      summary: Create new subdepartment of department with specified id
  759.      tags:
  760.        - Departments
  761.      security:
  762.      - ApiKeyAuth: []      
  763.      parameters:
  764.        - $ref: '#/components/parameters/departmentId'
  765.      requestBody:
  766.        description: New subdepartment description
  767.        required: true
  768.        content:
  769.          application/json:
  770.            schema:
  771.              type: object
  772.              properties:
  773.                title: { type: string }
  774.                adminId: { type: integer }
  775.              required: [ title, adminId ]
  776.      responses:
  777.        201:
  778.          description: New subdepartment successfully created, response contains its description
  779.          content: { application/json: { schema: { $ref: '#/components/schemas/Department' } } }
  780.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  781.        403: { $ref: '#/components/responses/NotAdminOrDepartmentAccessForbidden' }
  782.        404: { $ref: '#/components/responses/DepartmentNotFound' }
  783.  
  784.  /departments/{depid}/admin:
  785.    get:
  786.      tags:
  787.        - Departments
  788.        - Employees
  789.      summary: Get info about admin of department with specified id
  790.      security:
  791.        - ApiKeyAuth: []
  792.      parameters:
  793.        - $ref: '#/components/parameters/departmentId'
  794.        - $ref: '#/components/parameters/employeeFields'
  795.        - $ref: '#/components/parameters/start'
  796.        - $ref: '#/components/parameters/end'
  797.      responses:
  798.        200:
  799.          description: Information fetched successfully
  800.          content: { application/json: { schema: { $ref: '#/components/schemas/Employee' } } }
  801.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  802.        403: { $ref: '#/components/responses/NotAdminOrDepartmentAccessForbidden' }
  803.        404: { $ref: '#/components/responses/DepartmentNotFound' }
  804.    post:
  805.      tags:
  806.        - Departments
  807.        - Employees
  808.      summary: Assign admin to department with specified id
  809.      security:
  810.        - ApiKeyAuth: []
  811.      parameters:
  812.        - $ref: '#/components/parameters/departmentId'
  813.      requestBody:
  814.        description: New admin id
  815.        content:
  816.          application/json:
  817.            schema:
  818.              type: object
  819.              properties:
  820.                newAdminId: { type: integer, minimum: 1 }
  821.      responses:
  822.        201:
  823.          description: Admin assigned
  824.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  825.        403: { $ref: '#/components/responses/NotAdminOrEmployeeOrDepartmentAccessForbidden' }
  826.        404:
  827.          description: Specified department or employee wasn't found
  828.    delete:
  829.      tags:
  830.        - Departments
  831.        - Employees
  832.      summary: Unassign admin of department with specified id
  833.      security:
  834.        - ApiKeyAuth: []
  835.      parameters:
  836.        - $ref: '#/components/parameters/departmentId'
  837.      responses:
  838.        204:
  839.          description: Admin unassigned
  840.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  841.        403: { $ref: '#/components/responses/NotAdminOrDepartmentAccessForbidden' }
  842.        404: { $ref: '#/components/responses/DepartmentNotFound' }
  843.        422:
  844.          description: No admin is assigned to specified department
  845.  
  846.  /departments/{depId}/staff:
  847.    get:
  848.      tags:
  849.        - Departments
  850.        - Employees
  851.      summary: Get staff list of department width specified id
  852.      security:
  853.        - ApiKeyAuth: []
  854.      parameters:
  855.        - $ref: '#/components/parameters/departmentId'
  856.        - $ref: '#/components/parameters/employeeFields'
  857.        - $ref: '#/components/parameters/start'
  858.        - $ref: '#/components/parameters/end'
  859.      responses:
  860.        200:
  861.          description: Information fetched successfully
  862.          content:
  863.            application/json:
  864.              schema: { type: array, items: { $ref: '#/components/schemas/Employee' } }
  865.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  866.        403: { $ref: '#/components/responses/NotAdminOrDepartmentAccessForbidden' }
  867.        404: { $ref: '#/components/responses/DepartmentNotFound' }  
  868.    post:
  869.      tags:
  870.        - Departments
  871.        - Employees
  872.      summary: Invite new employee to department width specified id
  873.      security:
  874.        - ApiKeyAuth: []
  875.      parameters:
  876.        - $ref: '#/components/parameters/departmentId'
  877.      requestBody:
  878.        description: New employee description
  879.        content:
  880.          application/json:
  881.            schema:
  882.              type: object
  883.              properties:
  884.                name: { type: string }
  885.                email: { type: string, format: email }
  886.                photoUrl: { type: string, format: url }
  887.                position: { type: string }
  888.              required: [ name, email, position ]
  889.      responses:
  890.        201:
  891.          description: |
  892.            User successfully invited (new profile is created and e-main
  893.            with invitation sent)
  894.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  895.        403: { $ref: '#/components/responses/NotAdminOrDepartmentAccessForbidden' }
  896.        404: { $ref: '#/components/responses/DepartmentNotFound' }
  897.  
  898.  /hierarchy:
  899.    get:
  900.      summary: Get visible to current user hierarchial organisation structure
  901.      tags:
  902.        - Departments
  903.      security:
  904.        - ApiKeyAuth: []    
  905.      responses:
  906.        200:
  907.          description: Information successfully fetched
  908.          content: { application/json: { schema: { $ref: '#/components/schemas/DepartmentsHierarchyItem' } } }
  909.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  910.        403: { $ref: '#/components/responses/NotAdminAccessForbidden' }
  911.  
  912.  
  913.  # Employees specific endpoints #
  914.  /employees:
  915.    get:
  916.      tags:
  917.        - Employees
  918.      summary: Get suborinate employees list
  919.      security:
  920.        - ApiKeyAuth: []
  921.      parameters:
  922.        - $ref: '#/components/parameters/employeeFields'
  923.        - $ref: '#/components/parameters/start'
  924.        - $ref: '#/components/parameters/end'
  925.        - name: groupByDepartment
  926.          in: query
  927.          description: Whether to group employees in list by their departments
  928.          required: false
  929.          schema:
  930.            type: boolean
  931.            default: false
  932.      responses:
  933.        200:
  934.          description: |
  935.            Information fetched successfully, response body contains subordinate employees list
  936.            
  937.            Since viewer at swaggerhub doesn't display response body model if it's "oneOf", body
  938.            description is provided further.
  939.            Response structure varies depending on value of `groupByDepartment` parameters.
  940.  
  941.            **If `groupByDepartment` is false, then response is of the following structure:**
  942.            [Employee] — array of employees
  943.  
  944.            **If `groupByDepartment`is true, the response is of the following structure:**
  945.            ```
  946.            [{
  947.              department: { id: integer, title: string }
  948.              staff: [Employee]
  949.            }, {
  950.              ...
  951.            }]
  952.            ```
  953.          content:
  954.            application/json:
  955.              schema:
  956.                oneOf:
  957.                  - type: array
  958.                    items: { $ref: '#/components/schemas/Employee' }
  959.                  - type: array
  960.                    items:
  961.                      type: object
  962.                      properties:
  963.                        department: { type: object, properties: { id: { type: integer }, name: { type: string } } }
  964.                        staff: { type: array, items: { $ref: '#/components/schemas/Employee' } }
  965.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  966.  
  967.  /employees/{employeeId}:
  968.    get:
  969.      tags:
  970.        - Employees
  971.      summary: Get information about employee with specified id
  972.      security:
  973.        - ApiKeyAuth: []
  974.      parameters:
  975.        - $ref: '#/components/parameters/employeeId'
  976.        - $ref: '#/components/parameters/employeeFields'
  977.        - $ref: '#/components/parameters/start'
  978.        - $ref: '#/components/parameters/end'
  979.      responses:
  980.        200:
  981.          description: Information fetched successfully
  982.          content: { application/json: { schema: { $ref: '#/components/schemas/Employee' } } }
  983.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  984.        403: { $ref: '#/components/responses/NotAdminOrEmployeeAccessForbidden' }
  985.        404: { $ref: '#/components/responses/EmployeeNotFound' }
  986.    patch:
  987.      tags:
  988.        - Employees
  989.      summary: Update information about employee with specified id (currently goal)
  990.      security:
  991.        - ApiKeyAuth: []
  992.      parameters:
  993.        - $ref: '#/components/parameters/employeeId'
  994.      requestBody:
  995.        description: |
  996.          Employee patch document in JSON merge patch format
  997.  
  998.          Properties available for update:
  999.          * goal
  1000.        content:
  1001.          application/json:
  1002.            schema:
  1003.              type: object
  1004.              properties:
  1005.                goal:
  1006.                  type: object
  1007.                  properties:
  1008.                    name: { type: string }
  1009.                    type: { type: string, enum: [ concentration, relaxation ] }
  1010.      responses:
  1011.        200:
  1012.          description: Employee info updated, response contains object width updated properties
  1013.          content:
  1014.            application/json:
  1015.              schema:
  1016.                type: object
  1017.                properties:
  1018.                  title: { type: string }
  1019.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  1020.        403: { $ref: '#/components/responses/NotAdminOrEmployeeAccessForbidden' }
  1021.        404: { $ref: '#/components/responses/EmployeeNotFound' }
  1022.    delete:
  1023.      tags:
  1024.        - Employees
  1025.      summary: Delete employee
  1026.      security:
  1027.        - ApiKeyAuth: []
  1028.      parameters:
  1029.        - $ref: '#/components/parameters/employeeId'
  1030.      responses:
  1031.        204:
  1032.          description: Employee deleted
  1033.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  1034.        403: { $ref: '#/components/responses/NotAdminOrEmployeeAccessForbidden' }
  1035.        404: { $ref: '#/components/responses/EmployeeNotFound' }
  1036.          
  1037.  /employees/{employeeId}/department:
  1038.    get:
  1039.      tags:
  1040.        - Employees
  1041.        - Departments
  1042.      summary: Get information about department the user with specified id is a member of
  1043.      security:
  1044.        - ApiKeyAuth: []
  1045.      responses:
  1046.        200:
  1047.          description: Information successfully fetched
  1048.          content: { application/json: { schema: { $ref: '#/components/schemas/Department' } } }
  1049.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  1050.        403: { $ref: '#/components/responses/NotAdminOrEmployeeAccessForbidden' }
  1051.        404: { $ref: '#/components/responses/EmployeeNotFound' }
  1052.  
  1053.  # Rate endpoints #
  1054.  /rate:
  1055.    get:
  1056.      summary: Get ratings for period
  1057.      tags:
  1058.        - Rate
  1059.      security:
  1060.        - ApiKeyAuth: []
  1061.      parameters:
  1062.        - $ref: '#/components/parameters/start'
  1063.        - $ref: '#/components/parameters/end'
  1064.      responses:
  1065.        200:
  1066.          description: "Contains array of ratings for required period. If some of date was offday, then rating value will be -1"
  1067.          content:
  1068.            application/json:
  1069.              schema:
  1070.                type: array
  1071.                items: { $ref: '#/components/schemas/Rate' }
  1072.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  1073.        
  1074.    post:
  1075.      summary: Rate yourself
  1076.      tags:
  1077.        - Rate
  1078.      security:
  1079.        - ApiKeyAuth: []
  1080.      requestBody:
  1081.        description: "Rate is value [1 - 7], if rate is negative then this specified day of rating will be marked as offday.
  1082.           date field is required date of rating"
  1083.        content:
  1084.          application/json:
  1085.            schema: { $ref: '#/components/schemas/Rate' }
  1086.      responses:
  1087.        201: { description: "Successfully rated" }
  1088.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  1089.        409: { $ref: '#/components/responses/NoActiveGoalOrAlreadyRated' }
  1090.    
  1091.    patch:
  1092.      summary: change rate
  1093.      tags:
  1094.        - Rate
  1095.      security:
  1096.        - ApiKeyAuth: []
  1097.      requestBody:
  1098.        description: "Rate is value [1 - 7], if rate is negative then this specified day of rating will be marked as offday.
  1099.           date field is required date of rating"
  1100.        content:
  1101.          application/json:
  1102.            schema: { $ref: '#/components/schemas/Rate' }
  1103.      responses:
  1104.        200: { description: Successfully updated }
  1105.        404: { $ref: '#/components/responses/RateNotFound' }
  1106.      
  1107.  
  1108.  # Other endpoints #    
  1109.  /dashboard:
  1110.    get:
  1111.      summary: Fetch dashboard data
  1112.      tags:
  1113.        - Other
  1114.      security:
  1115.        - ApiKeyAuth: []
  1116.      parameters:
  1117.        - $ref: '#/components/parameters/start'
  1118.        - $ref: '#/components/parameters/end'
  1119.      responses:
  1120.        200:
  1121.          description: OK
  1122.          content: { application/json: { schema: { $ref: '#/components/schemas/DashboardContent' } } }
  1123.        401: { $ref: '#/components/responses/UserIsUnauthenticated' }
  1124.        403: { $ref: '#/components/responses/NotAdminAccessForbidden' }
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement
Public Pastes
Advertisement
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy.  OK, I Understand
Not a member of Pastebin yet?
Sign Up, it unlocks many cool features!