API tools faq
paste
Advertisement
Guest User

Untitled

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