PMT-9: Add Employee API Doc Localy (With Bugfixes)
This commit is contained in:
parent
88c1b196b1
commit
b04ab575cf
GPG key ID:
67D15BB250B41E7C
1 changed files with 473 additions and 0 deletions
473
api/employee.yml
Normal file
473
api/employee.yml
Normal file
|
|
@ -0,0 +1,473 @@
|
||||||
|
openapi: 3.0.1
|
||||||
|
info:
|
||||||
|
title: Employees Management Micro-Service
|
||||||
|
description: "\n## Overview\n\nEmployees Management Service API manages the employees\
|
||||||
|
\ of HighTec Gmbh including their qualifications. It offers the possibility to\
|
||||||
|
\ create, read, update and delete employees and qualifications. Existing employees\
|
||||||
|
\ can be assigned new qualifications or have them withdrawn. \nThe API is organized\
|
||||||
|
\ around REST. It has predictable resource-oriented URLs, accepts JSON-encoded\
|
||||||
|
\ request bodies, returns JSON-encoded responses, uses standard HTTP response\
|
||||||
|
\ codes and authentication.\n\n## Authentication\n\nEmployees Management Service\
|
||||||
|
\ API uses JWTs to authenticate requests. You will receive a bearer token by making\
|
||||||
|
\ a POST-Request in IntelliJ on:\n\n\n```\nPOST http://keycloak.szut.dev/auth/realms/szut/protocol/openid-connect/token\n\
|
||||||
|
Content-Type: application/x-www-form-urlencoded\ngrant_type=password&client_id=employee-management-service&username=user&password=test\n\
|
||||||
|
```\n\n\nor by CURL\n```\ncurl -X POST 'http://keycloak.szut.dev/auth/realms/szut/protocol/openid-connect/token'\n\
|
||||||
|
--header 'Content-Type: application/x-www-form-urlencoded'\n--data-urlencode 'grant_type=password'\n\
|
||||||
|
--data-urlencode 'client_id=employee-management-service'\n--data-urlencode 'username=user'\n\
|
||||||
|
--data-urlencode 'password=test'\n```\n\nTo get a bearer-token in Postman, you\
|
||||||
|
\ have to follow the instructions in \n [Postman-Documentation](https://documenter.getpostman.com/view/7294517/SzmfZHnd).\n\
|
||||||
|
\nAll API requests must be made over HTTPS. Calls made over plain HTTP will fail.\
|
||||||
|
\ API requests without authentication will also fail. Each request has the URL\
|
||||||
|
\ \n `https://employee.szut.dev` and the address of the desired resource."
|
||||||
|
version: 1.0.1
|
||||||
|
servers:
|
||||||
|
- url: ""
|
||||||
|
security:
|
||||||
|
- bearerAuth: []
|
||||||
|
paths:
|
||||||
|
/qualifications/{id}:
|
||||||
|
put:
|
||||||
|
tags:
|
||||||
|
- qualification-controller
|
||||||
|
summary: updates a qualification
|
||||||
|
operationId: updateQualification
|
||||||
|
parameters:
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
requestBody:
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/QualificationPostDTO'
|
||||||
|
required: true
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"400":
|
||||||
|
description: invalid JSON posted
|
||||||
|
"200":
|
||||||
|
description: updated qualification
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/QualificationPostDTO'
|
||||||
|
"404":
|
||||||
|
description: resource not found
|
||||||
|
delete:
|
||||||
|
tags:
|
||||||
|
- qualification-controller
|
||||||
|
summary: deletes a qualification by id
|
||||||
|
operationId: deleteQualificationByDesignation
|
||||||
|
parameters:
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"403":
|
||||||
|
description: qualification is in use
|
||||||
|
"204":
|
||||||
|
description: delete successful
|
||||||
|
"404":
|
||||||
|
description: resource not found
|
||||||
|
/employees/{id}:
|
||||||
|
get:
|
||||||
|
tags:
|
||||||
|
- employee-controller
|
||||||
|
summary: find employee by id
|
||||||
|
operationId: findById
|
||||||
|
parameters:
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"200":
|
||||||
|
description: employee
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/EmployeeResponseDTO'
|
||||||
|
"404":
|
||||||
|
description: resource not found
|
||||||
|
put:
|
||||||
|
tags:
|
||||||
|
- employee-controller
|
||||||
|
summary: updates employee by id - only changes the fields that are posted
|
||||||
|
operationId: updateEmployee
|
||||||
|
parameters:
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
requestBody:
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/EmployeeRequestPutDTO'
|
||||||
|
required: true
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"200":
|
||||||
|
description: employee
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/EmployeeResponseDTO'
|
||||||
|
"404":
|
||||||
|
description: resource not found
|
||||||
|
delete:
|
||||||
|
tags:
|
||||||
|
- employee-controller
|
||||||
|
summary: deletes a employee by id
|
||||||
|
operationId: deleteCustomer
|
||||||
|
parameters:
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"204":
|
||||||
|
description: delete successful
|
||||||
|
"404":
|
||||||
|
description: resource not found
|
||||||
|
/qualifications:
|
||||||
|
get:
|
||||||
|
tags:
|
||||||
|
- qualification-controller
|
||||||
|
summary: delivers a list of all available qualifications
|
||||||
|
operationId: findAll
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"200":
|
||||||
|
description: list of qualifications
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/QualificationPostDTO'
|
||||||
|
post:
|
||||||
|
tags:
|
||||||
|
- qualification-controller
|
||||||
|
summary: creates a new qualification with its id and designation
|
||||||
|
operationId: createQualification
|
||||||
|
requestBody:
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/QualificationPostDTO'
|
||||||
|
required: true
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"201":
|
||||||
|
description: created qualification
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/QualificationPostDTO'
|
||||||
|
"400":
|
||||||
|
description: invalid JSON posted
|
||||||
|
/employees:
|
||||||
|
get:
|
||||||
|
tags:
|
||||||
|
- employee-controller
|
||||||
|
summary: delivers a list of all employees
|
||||||
|
operationId: findAll_1
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"200":
|
||||||
|
description: list of employees
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/EmployeeResponseDTO'
|
||||||
|
post:
|
||||||
|
tags:
|
||||||
|
- employee-controller
|
||||||
|
summary: creates a new employee
|
||||||
|
operationId: createEmployee
|
||||||
|
requestBody:
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/EmployeeRequestDTO'
|
||||||
|
required: true
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"400":
|
||||||
|
description: invalid JSON posted
|
||||||
|
"201":
|
||||||
|
description: created employee
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/EmployeeResponseDTO'
|
||||||
|
/employees/{id}/qualifications:
|
||||||
|
get:
|
||||||
|
tags:
|
||||||
|
- employee-controller
|
||||||
|
summary: finds all qualifications of an employee by id
|
||||||
|
operationId: findAllQualificationOfAEmployeeById
|
||||||
|
parameters:
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"200":
|
||||||
|
description: employee with a list of his qualifications
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/EmployeeNameAndSkillDataDTO'
|
||||||
|
"404":
|
||||||
|
description: resource not found
|
||||||
|
post:
|
||||||
|
tags:
|
||||||
|
- employee-controller
|
||||||
|
summary: adds a qualification to an employee by id
|
||||||
|
operationId: addQualificationToEmployeeById
|
||||||
|
parameters:
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
requestBody:
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/QualificationPostDTO'
|
||||||
|
required: true
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"400":
|
||||||
|
description: invalid JSON posted or employee already has this qualification
|
||||||
|
"200":
|
||||||
|
description: employee with a list of his qualifications
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/EmployeeNameAndSkillDataDTO'
|
||||||
|
"404":
|
||||||
|
description: resource not found
|
||||||
|
delete:
|
||||||
|
tags:
|
||||||
|
- employee-controller
|
||||||
|
summary: deletes a qualification of an employee by id
|
||||||
|
operationId: removeQualificationFromEmployee
|
||||||
|
parameters:
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
requestBody:
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/QualificationPostDTO'
|
||||||
|
required: true
|
||||||
|
responses:
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"200":
|
||||||
|
description: employee with a list of his qualifications
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/EmployeeNameAndSkillDataDTO'
|
||||||
|
"404":
|
||||||
|
description: resource not found
|
||||||
|
/qualifications/{id}/employees:
|
||||||
|
get:
|
||||||
|
tags:
|
||||||
|
- qualification-controller
|
||||||
|
summary: find employees by qualification id
|
||||||
|
operationId: findAllEmployeesByQualification
|
||||||
|
parameters:
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
responses:
|
||||||
|
"200":
|
||||||
|
description: List of employees who have the desired qualification
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/EmployeesForAQualificationDTO'
|
||||||
|
"401":
|
||||||
|
description: not authorized
|
||||||
|
"404":
|
||||||
|
description: qualification id does not exist
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
QualificationPostDTO:
|
||||||
|
required:
|
||||||
|
- skill
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
skill:
|
||||||
|
type: string
|
||||||
|
EmployeeRequestPutDTO:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
lastName:
|
||||||
|
type: string
|
||||||
|
firstName:
|
||||||
|
type: string
|
||||||
|
street:
|
||||||
|
type: string
|
||||||
|
postcode:
|
||||||
|
type: string
|
||||||
|
city:
|
||||||
|
type: string
|
||||||
|
phone:
|
||||||
|
type: string
|
||||||
|
skillSet:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
EmployeeResponseDTO:
|
||||||
|
required:
|
||||||
|
- city
|
||||||
|
- firstName
|
||||||
|
- lastName
|
||||||
|
- phone
|
||||||
|
- postcode
|
||||||
|
- street
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
lastName:
|
||||||
|
type: string
|
||||||
|
firstName:
|
||||||
|
type: string
|
||||||
|
street:
|
||||||
|
type: string
|
||||||
|
postcode:
|
||||||
|
maxLength: 5
|
||||||
|
minLength: 5
|
||||||
|
type: string
|
||||||
|
city:
|
||||||
|
type: string
|
||||||
|
phone:
|
||||||
|
type: string
|
||||||
|
skillSet:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/QualificationGetDTO'
|
||||||
|
QualificationGetDTO:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
skill:
|
||||||
|
type: string
|
||||||
|
id:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
EmployeeRequestDTO:
|
||||||
|
required:
|
||||||
|
- city
|
||||||
|
- firstName
|
||||||
|
- lastName
|
||||||
|
- phone
|
||||||
|
- postcode
|
||||||
|
- street
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
lastName:
|
||||||
|
type: string
|
||||||
|
firstName:
|
||||||
|
type: string
|
||||||
|
street:
|
||||||
|
type: string
|
||||||
|
postcode:
|
||||||
|
maxLength: 5
|
||||||
|
minLength: 5
|
||||||
|
type: string
|
||||||
|
city:
|
||||||
|
type: string
|
||||||
|
phone:
|
||||||
|
type: string
|
||||||
|
skillSet:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
EmployeeNameAndSkillDataDTO:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
lastName:
|
||||||
|
type: string
|
||||||
|
firstName:
|
||||||
|
type: string
|
||||||
|
skillSet:
|
||||||
|
uniqueItems: true
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/QualificationPostDTO'
|
||||||
|
EmployeeNameDataDTO:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
lastName:
|
||||||
|
type: string
|
||||||
|
firstName:
|
||||||
|
type: string
|
||||||
|
EmployeesForAQualificationDTO:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
qualification:
|
||||||
|
$ref: '#/components/schemas/QualificationGetDTO'
|
||||||
|
employees:
|
||||||
|
uniqueItems: true
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/EmployeeNameDataDTO'
|
||||||
|
securitySchemes:
|
||||||
|
bearerAuth:
|
||||||
|
type: http
|
||||||
|
scheme: bearer
|
||||||
|
bearerFormat: JWT
|
||||||
Loading…
Reference in a new issue