From cbbf1e6aa7e8e87ddb31a02b0025213717c5cab5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Tailland?= Date: Wed, 26 Aug 2026 18:28:25 +0200 Subject: [PATCH] Add the OpenAPI spec for the customers domain MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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://customers-dev.sttlab.local/customers/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 --- openapi.yaml | 577 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 577 insertions(+) create mode 100644 openapi.yaml diff --git a/openapi.yaml b/openapi.yaml new file mode 100644 index 0000000..1c4bc5b --- /dev/null +++ b/openapi.yaml @@ -0,0 +1,577 @@ +openapi: 3.0.3 +info: + title: Classic Models API — Customers domain + version: 4.7.0 + description: 'Customer accounts, contacts and credit limits. Customers domain subset of the shared classic-models-api backend, as exposed by the customers domain''s Kong gateway. Paths and server below are the gateway''s, not the backend''s: the gateway rewrites /customers/v1/... onto /classic-models/api/v1/... upstream. Requires a bearer token from the classic-models realm.' +paths: + /customers/v1/customers/: + get: + operationId: list_customers + description: Retrieve a paginated list of all customers with their contact and credit information. + summary: List all customers + 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: + - Customers + security: + - ApiKeyAuth: [] + - JWTAuth: [] + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedCustomerList' + description: "" + post: + operationId: create_customer + description: Add a new customer to the system with their contact details and credit limit. + summary: Create a new customer + tags: + - Customers + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CustomerRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/CustomerRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/CustomerRequest' + required: true + security: + - ApiKeyAuth: [] + - JWTAuth: [] + responses: + "201": + content: + application/json: + schema: + $ref: '#/components/schemas/Customer' + description: "" + /customers/v1/customers/{customernumber}/: + get: + operationId: get_customer + description: Retrieve detailed information about a specific customer by their customer number. + summary: Get a specific customer + parameters: + - in: path + name: customernumber + schema: + type: integer + maximum: 2147483647 + minimum: -2147483648 + description: A unique value identifying this customer. + required: true + tags: + - Customers + security: + - ApiKeyAuth: [] + - JWTAuth: [] + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Customer' + description: "" + patch: + operationId: patch_customer + description: Update specific fields of an existing customer record. + summary: Partially update a customer + parameters: + - in: path + name: customernumber + schema: + type: integer + maximum: 2147483647 + minimum: -2147483648 + description: A unique value identifying this customer. + required: true + tags: + - Customers + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PatchedCustomerRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedCustomerRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedCustomerRequest' + security: + - ApiKeyAuth: [] + - JWTAuth: [] + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Customer' + description: "" + delete: + operationId: delete_customer + description: Remove a customer from the system. + summary: Delete a customer + parameters: + - in: path + name: customernumber + schema: + type: integer + maximum: 2147483647 + minimum: -2147483648 + description: A unique value identifying this customer. + required: true + tags: + - Customers + security: + - ApiKeyAuth: [] + - JWTAuth: [] + responses: + "204": + description: No response body + put: + operationId: update_customer + description: Update all fields of an existing customer record. + summary: Update a customer + parameters: + - in: path + name: customernumber + schema: + type: integer + maximum: 2147483647 + minimum: -2147483648 + description: A unique value identifying this customer. + required: true + tags: + - Customers + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CustomerRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/CustomerRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/CustomerRequest' + required: true + security: + - ApiKeyAuth: [] + - JWTAuth: [] + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Customer' + description: "" + /customers/v1/customers/{customernumber}/orders/: + get: + operationId: get_customer_orders + description: Retrieve all orders for a specific customer. This endpoint provides the complete sales history for the customer. + summary: Get customer sales history + parameters: + - in: path + name: customernumber + schema: + type: integer + description: The customer number + 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: + - Customers + security: + - ApiKeyAuth: [] + - JWTAuth: [] + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedOrderList' + description: "" + /customers/v1/customers/{customernumber}/payments/: + get: + operationId: get_customer_payments + description: Retrieve all payments made by a specific customer. This endpoint provides the complete payment history for the customer. + summary: Get customer payment history + parameters: + - in: path + name: customernumber + schema: + type: integer + description: The customer number + 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: + - Customers + security: + - ApiKeyAuth: [] + - JWTAuth: [] + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedPaymentList' + 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 + CustomerRequest: + type: object + description: Customer information and contact details + properties: + customernumber: + type: integer + maximum: 2147483647 + minimum: -2147483648 + customername: + type: string + minLength: 1 + maxLength: 50 + contactlastname: + type: string + minLength: 1 + maxLength: 50 + contactfirstname: + 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 + city: + type: string + minLength: 1 + maxLength: 50 + state: + type: string + nullable: true + maxLength: 50 + postalcode: + type: string + nullable: true + maxLength: 15 + country: + type: string + minLength: 1 + 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 + Order: + type: object + description: Customer order information + properties: + ordernumber: + type: integer + maximum: 2147483647 + minimum: -2147483648 + orderdate: + type: string + format: date + requireddate: + type: string + format: date + shippeddate: + type: string + format: date + nullable: true + status: + type: string + maxLength: 15 + comments: + type: string + nullable: true + customernumber: + type: integer + maximum: 2147483647 + minimum: -2147483648 + required: + - customernumber + - orderdate + - ordernumber + - requireddate + - status + 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' + PaginatedOrderList: + 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/Order' + PaginatedPaymentList: + 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/Payment' + PatchedCustomerRequest: + type: object + description: Customer information and contact details + properties: + customernumber: + type: integer + maximum: 2147483647 + minimum: -2147483648 + customername: + type: string + minLength: 1 + maxLength: 50 + contactlastname: + type: string + minLength: 1 + maxLength: 50 + contactfirstname: + 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 + city: + type: string + minLength: 1 + maxLength: 50 + state: + type: string + nullable: true + maxLength: 50 + postalcode: + type: string + nullable: true + maxLength: 15 + country: + type: string + minLength: 1 + 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 + Payment: + type: object + description: Customer payment records + properties: + id: + type: integer + readOnly: true + checknumber: + type: string + maxLength: 50 + paymentdate: + type: string + format: date + amount: + type: string + format: decimal + pattern: ^-?\d{0,8}(?:\.\d{0,2})?$ + customernumber: + type: integer + maximum: 2147483647 + minimum: -2147483648 + required: + - amount + - checknumber + - customernumber + - id + - paymentdate + 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://customers-dev.sttlab.local + description: Customers gateway (dev)