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