stt/kong-workforce-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add the OpenAPI spec for the workforce domain

Browse Source 
The developer portal listed this API with no reference documentation:
catalog was the only domain that had a spec anywhere in the tree.

Generated from the backend's own drf-spectacular schema
(/classic-models/api/schema/, version 4.7.0), filtered to the operations
this domain's gateway actually exposes — derived from the Kong routes and
their request-transformer rewrites in Konnect, not from guesswork. Every
route resolved to a backend operation; the counts match one for one.

Paths and server are the **gateway's**, not the backend's. A portal
reader calls https://workforce-dev.sttlab.local/workforce/v1/..., and the
gateway rewrites that onto /classic-models/api/v1/... upstream. Path
parameters are renamed to the gateway's capture names where the backend
used a different case.

Components are pruned to what these paths transitively reference.

Note: catalog-api/openapi.yaml does NOT follow this convention — it
documents the backend paths and http://localhost:8000 as its server, so
its operations cannot be called as written from the portal. Left alone
here; worth aligning separately.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Stéphane Tailland
2026-08-26 18:28:25 +02:00
parent 85dddaec9d
commit dad30481e3
1 changed files with 844 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openapi.yaml
+844
View File
@@ -0,0 +1,844 @@
openapi: 3.0.3
info:
title: Classic Models API — Workforce domain
version: 4.7.0
description: 'Offices, employees and the reporting hierarchy. Workforce domain subset of the shared classic-models-api backend, as exposed by the workforce domain''s Kong gateway. Paths and server below are the gateway''s, not the backend''s: the gateway rewrites /workforce/v1/... onto /classic-models/api/v1/... upstream. Requires a bearer token from the classic-models realm.'
paths:
/workforce/v1/employees/:
post:
operationId: create_employee
description: Add a new employee to the organization with their job details and office assignment.
summary: Create a new employee
tags:
- Employees
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/EmployeeRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/EmployeeRequest'
required: true
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/Employee'
description: ""
get:
operationId: list_employees
description: Retrieve a paginated list of all employees in the organization with their details.
summary: List all employees
parameters:
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- name: page_size
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
tags:
- Employees
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedEmployeeList'
description: ""
/workforce/v1/employees/{employeenumber}/:
patch:
operationId: patch_employee
description: Update specific fields of an existing employee record.
summary: Partially update an employee
parameters:
- in: path
name: employeenumber
schema:
type: integer
maximum: 2147483647
minimum: -2147483648
description: A unique value identifying this employee.
required: true
tags:
- Employees
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedEmployeeRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedEmployeeRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedEmployeeRequest'
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Employee'
description: ""
put:
operationId: update_employee
description: Update all fields of an existing employee record.
summary: Update an employee
parameters:
- in: path
name: employeenumber
schema:
type: integer
maximum: 2147483647
minimum: -2147483648
description: A unique value identifying this employee.
required: true
tags:
- Employees
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/EmployeeRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/EmployeeRequest'
required: true
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Employee'
description: ""
get:
operationId: get_employee
description: Retrieve detailed information about a specific employee by their employee number.
summary: Get a specific employee
parameters:
- in: path
name: employeenumber
schema:
type: integer
maximum: 2147483647
minimum: -2147483648
description: A unique value identifying this employee.
required: true
tags:
- Employees
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Employee'
description: ""
delete:
operationId: delete_employee
description: Remove an employee from the organization.
summary: Delete an employee
parameters:
- in: path
name: employeenumber
schema:
type: integer
maximum: 2147483647
minimum: -2147483648
description: A unique value identifying this employee.
required: true
tags:
- Employees
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"204":
description: No response body
/workforce/v1/employees/{employeenumber}/customers/:
get:
operationId: get_employee_customers
description: Retrieve all customers assigned to a specific sales representative. This endpoint supports sales rep performance tracking and customer management.
summary: Get customers by sales rep
parameters:
- in: path
name: employeenumber
schema:
type: integer
description: The employee number of the sales representative
required: true
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- name: page_size
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
tags:
- Employees
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCustomerList'
description: ""
/workforce/v1/employees/{employeenumber}/reports/:
get:
operationId: get_employee_reports
description: Retrieve all employees reporting to a specific manager. This endpoint supports organizational hierarchy and team management.
summary: Get employees by manager
parameters:
- in: path
name: employeenumber
schema:
type: integer
description: The employee number of the manager
required: true
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- name: page_size
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
tags:
- Employees
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedEmployeeList'
description: ""
/workforce/v1/offices/:
post:
operationId: create_office
description: Add a new office location to the company's network.
summary: Create a new office
tags:
- Offices
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OfficeRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/OfficeRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/OfficeRequest'
required: true
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/Office'
description: ""
get:
operationId: list_offices
description: Retrieve a paginated list of all company office locations worldwide.
summary: List all offices
parameters:
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- name: page_size
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
tags:
- Offices
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedOfficeList'
description: ""
/workforce/v1/offices/{officecode}/:
patch:
operationId: patch_office
description: Update specific fields of an existing office location.
summary: Partially update an office
parameters:
- in: path
name: officecode
schema:
type: string
description: A unique value identifying this office.
required: true
tags:
- Offices
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedOfficeRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedOfficeRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedOfficeRequest'
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Office'
description: ""
put:
operationId: update_office
description: Update all fields of an existing office location.
summary: Update an office
parameters:
- in: path
name: officecode
schema:
type: string
description: A unique value identifying this office.
required: true
tags:
- Offices
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OfficeRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/OfficeRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/OfficeRequest'
required: true
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Office'
description: ""
get:
operationId: get_office
description: Retrieve detailed information about a specific office by its code.
summary: Get a specific office
parameters:
- in: path
name: officecode
schema:
type: string
description: A unique value identifying this office.
required: true
tags:
- Offices
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Office'
description: ""
delete:
operationId: delete_office
description: Remove an office location from the company network.
summary: Delete an office
parameters:
- in: path
name: officecode
schema:
type: string
description: A unique value identifying this office.
required: true
tags:
- Offices
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"204":
description: No response body
/workforce/v1/offices/{officecode}/employees/:
get:
operationId: get_office_employees
description: Retrieve all employees working in a specific office. This endpoint supports office management and organizational charts.
summary: Get employees by office
parameters:
- in: path
name: officecode
schema:
type: string
description: The office code
required: true
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- name: page_size
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
tags:
- Offices
security:
- ApiKeyAuth: []
- JWTAuth: []
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedEmployeeList'
description: ""
components:
schemas:
Customer:
type: object
description: Customer information and contact details
properties:
customernumber:
type: integer
maximum: 2147483647
minimum: -2147483648
customername:
type: string
maxLength: 50
contactlastname:
type: string
maxLength: 50
contactfirstname:
type: string
maxLength: 50
phone:
type: string
maxLength: 50
addressline1:
type: string
maxLength: 50
addressline2:
type: string
nullable: true
maxLength: 50
city:
type: string
maxLength: 50
state:
type: string
nullable: true
maxLength: 50
postalcode:
type: string
nullable: true
maxLength: 15
country:
type: string
maxLength: 50
creditlimit:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
nullable: true
salesrepemployeenumber:
type: integer
maximum: 2147483647
minimum: -2147483648
nullable: true
required:
- addressline1
- city
- contactfirstname
- contactlastname
- country
- customername
- customernumber
- phone
Employee:
type: object
description: Employee information and hierarchy
properties:
employeenumber:
type: integer
maximum: 2147483647
minimum: -2147483648
lastname:
type: string
maxLength: 50
firstname:
type: string
maxLength: 50
extension:
type: string
maxLength: 10
email:
type: string
maxLength: 100
jobtitle:
type: string
maxLength: 50
officecode:
type: string
reportsto:
type: integer
maximum: 2147483647
minimum: -2147483648
nullable: true
required:
- email
- employeenumber
- extension
- firstname
- jobtitle
- lastname
- officecode
EmployeeRequest:
type: object
description: Employee information and hierarchy
properties:
employeenumber:
type: integer
maximum: 2147483647
minimum: -2147483648
lastname:
type: string
minLength: 1
maxLength: 50
firstname:
type: string
minLength: 1
maxLength: 50
extension:
type: string
minLength: 1
maxLength: 10
email:
type: string
minLength: 1
maxLength: 100
jobtitle:
type: string
minLength: 1
maxLength: 50
officecode:
type: string
minLength: 1
reportsto:
type: integer
maximum: 2147483647
minimum: -2147483648
nullable: true
required:
- email
- employeenumber
- extension
- firstname
- jobtitle
- lastname
- officecode
Office:
type: object
description: Company office locations
properties:
officecode:
type: string
maxLength: 10
city:
type: string
maxLength: 50
phone:
type: string
maxLength: 50
addressline1:
type: string
maxLength: 50
addressline2:
type: string
nullable: true
maxLength: 50
state:
type: string
nullable: true
maxLength: 50
country:
type: string
maxLength: 50
postalcode:
type: string
maxLength: 15
territory:
type: string
maxLength: 10
required:
- addressline1
- city
- country
- officecode
- phone
- postalcode
- territory
OfficeRequest:
type: object
description: Company office locations
properties:
officecode:
type: string
minLength: 1
maxLength: 10
city:
type: string
minLength: 1
maxLength: 50
phone:
type: string
minLength: 1
maxLength: 50
addressline1:
type: string
minLength: 1
maxLength: 50
addressline2:
type: string
nullable: true
maxLength: 50
state:
type: string
nullable: true
maxLength: 50
country:
type: string
minLength: 1
maxLength: 50
postalcode:
type: string
minLength: 1
maxLength: 15
territory:
type: string
minLength: 1
maxLength: 10
required:
- addressline1
- city
- country
- officecode
- phone
- postalcode
- territory
PaginatedCustomerList:
type: object
properties:
count:
type: integer
example: 123
next:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=4
previous:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=2
results:
type: array
items:
$ref: '#/components/schemas/Customer'
PaginatedEmployeeList:
type: object
properties:
count:
type: integer
example: 123
next:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=4
previous:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=2
results:
type: array
items:
$ref: '#/components/schemas/Employee'
PaginatedOfficeList:
type: object
properties:
count:
type: integer
example: 123
next:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=4
previous:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=2
results:
type: array
items:
$ref: '#/components/schemas/Office'
PatchedEmployeeRequest:
type: object
description: Employee information and hierarchy
properties:
employeenumber:
type: integer
maximum: 2147483647
minimum: -2147483648
lastname:
type: string
minLength: 1
maxLength: 50
firstname:
type: string
minLength: 1
maxLength: 50
extension:
type: string
minLength: 1
maxLength: 10
email:
type: string
minLength: 1
maxLength: 100
jobtitle:
type: string
minLength: 1
maxLength: 50
officecode:
type: string
minLength: 1
reportsto:
type: integer
maximum: 2147483647
minimum: -2147483648
nullable: true
PatchedOfficeRequest:
type: object
description: Company office locations
properties:
officecode:
type: string
minLength: 1
maxLength: 10
city:
type: string
minLength: 1
maxLength: 50
phone:
type: string
minLength: 1
maxLength: 50
addressline1:
type: string
minLength: 1
maxLength: 50
addressline2:
type: string
nullable: true
maxLength: 50
state:
type: string
nullable: true
maxLength: 50
country:
type: string
minLength: 1
maxLength: 50
postalcode:
type: string
minLength: 1
maxLength: 15
territory:
type: string
minLength: 1
maxLength: 10
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key authentication using X-API-Key header
JWTAuth:
type: http
scheme: bearer
bearerFormat: JWT
servers:
- url: https://workforce-dev.sttlab.local
description: Workforce gateway (dev)