From b00f65d6d55571ad601659e1286787b976ffc1ba Mon Sep 17 00:00:00 2001 From: Mike Stankavich Date: Sat, 16 May 2026 07:54:22 -0500 Subject: [PATCH] =?UTF-8?q?docs(api):=20TRA-742=20BB43=20F1+F2=20=E2=80=94?= =?UTF-8?q?=20info.contact.url=20+=20external=5Fkey=20symmetry=20sweep?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Syncs trakrf/platform@24db422. Spec edits batched in the platform PR: F1 — info.contact.url: was https://app.trakrf.id/api (SPA HTML shell), now https://docs.trakrf.id/ (docs site). With the literal app.trakrf.id/api gone from the spec, the three contact-URL swap mechanisms (platform runtime, refresh-openapi.sh DEPLOY_ENV=preview block, swap-openapi-env.mjs postbuild) all silently no-op; docs-mirror and platform-served copies remain byte-identical without any platform-side code change. F2 — CreateAssetWithTagsRequest.external_key gains description + example parallel to CreateLocationWithTagsRequest.external_key. Sweep — 5 additional Asset/Location asymmetries surfaced and batched per the up-to-5 rule: CreateAssetWithTagsRequest description+name examples; UpdateAssetRequest description+is_active+name examples. Tag*Request variants and *View response schemas reviewed and confirmed symmetric. Cleanup follow-up (not in this PR): swap-openapi-env.mjs and the DEPLOY_ENV=preview block in refresh-openapi.sh are now permanently no-op and can be removed in a follow-up; their only job was swapping the app.trakrf.id/api literal that no longer appears in the spec. Co-Authored-By: Claude Opus 4.7 (1M context) --- static/api/openapi.json | 9 ++++++++- static/api/openapi.yaml | 12 +++++++++++- static/api/platform-meta.json | 6 +++--- 3 files changed, 22 insertions(+), 5 deletions(-) diff --git a/static/api/openapi.json b/static/api/openapi.json index 42dc02d..1230185 100644 --- a/static/api/openapi.json +++ b/static/api/openapi.json @@ -461,6 +461,7 @@ "additionalProperties": false, "properties": { "description": { + "example": "Main warehouse forklift", "maxLength": 1024, "minLength": 1, "nullable": true, @@ -468,6 +469,8 @@ "type": "string" }, "external_key": { + "description": "external_key is optional. Omit to receive a server-assigned key in the\nformat ASSET-NNNN (per-organization sequence). When supplied, must\nsatisfy the external_key_pattern.", + "example": "forklift-3", "maxLength": 255, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", @@ -482,6 +485,7 @@ "type": "object" }, "name": { + "example": "Forklift 3", "maxLength": 255, "minLength": 1, "pattern": "^[^\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F]*$", @@ -1184,6 +1188,7 @@ "UpdateAssetRequest": { "properties": { "description": { + "example": "Updated description", "maxLength": 1024, "minLength": 1, "nullable": true, @@ -1191,6 +1196,7 @@ "type": "string" }, "is_active": { + "example": true, "type": "boolean" }, "metadata": { @@ -1198,6 +1204,7 @@ "type": "object" }, "name": { + "example": "Forklift 3", "maxLength": 255, "minLength": 1, "pattern": "^[^\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F]*$", @@ -1303,7 +1310,7 @@ "contact": { "email": "support@trakrf.id", "name": "TrakRF Support", - "url": "https://app.trakrf.id/api" + "url": "https://docs.trakrf.id/" }, "description": "TrakRF public REST API. See /api for the customer-facing reference.\n\nSpec available as YAML (/api/openapi.yaml) and JSON (/api/openapi.json).\n\nHTTP method coverage (HEAD, OPTIONS, 405 / Allow): /api/http-method-coverage\n\nSurrogate ID width: declared `format: int64` on the wire so SDK regeneration does not break when the ID namespace eventually outgrows int32. Service-side ID generation stays within int32 (2^31-1) during v1; values above that bound are rejected with 400 validation_error / `too_large`. The wider wire type is a long-horizon contract, not a claim that current values exceed int32.\n\nNullable field interpretation: OpenAPI 3.0's `nullable: true` keyword is interpreted differently across codegen targets. Verified-working: `openapi-typescript@7.x` emits `string | null` correctly, and the `openapi-generator-cli` python target emits `Optional[StrictStr]` correctly — both round-trip CRUD against null-bearing responses unmodified. Known-broken: `datamodel-codegen@0.57.0` emits `nullable: true` read-shape fields as non-Optional required fields, so Pydantic validation fails on every nullable field that is actually null. Integrators using `datamodel-codegen` should either switch to the `openapi-generator-cli` python target or apply `--use-annotated --use-union-operator` with a custom post-processing pass.", "license": { diff --git a/static/api/openapi.yaml b/static/api/openapi.yaml index d7ed70e..3363151 100644 --- a/static/api/openapi.yaml +++ b/static/api/openapi.yaml @@ -339,12 +339,18 @@ components: additionalProperties: false properties: description: + example: Main warehouse forklift maxLength: 1024 minLength: 1 nullable: true pattern: ^[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]*$ type: string external_key: + description: |- + external_key is optional. Omit to receive a server-assigned key in the + format ASSET-NNNN (per-organization sequence). When supplied, must + satisfy the external_key_pattern. + example: forklift-3 maxLength: 255 minLength: 1 pattern: ^[A-Za-z0-9-]+$ @@ -356,6 +362,7 @@ components: additionalProperties: {} type: object name: + example: Forklift 3 maxLength: 255 minLength: 1 pattern: ^[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]*$ @@ -880,17 +887,20 @@ components: UpdateAssetRequest: properties: description: + example: Updated description maxLength: 1024 minLength: 1 nullable: true pattern: ^[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]*$ type: string is_active: + example: true type: boolean metadata: additionalProperties: {} type: object name: + example: Forklift 3 maxLength: 255 minLength: 1 pattern: ^[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]*$ @@ -970,7 +980,7 @@ info: contact: email: support@trakrf.id name: TrakRF Support - url: https://app.trakrf.id/api + url: https://docs.trakrf.id/ description: |- TrakRF public REST API. See /api for the customer-facing reference. diff --git a/static/api/platform-meta.json b/static/api/platform-meta.json index 5fd39de..4cb0937 100644 --- a/static/api/platform-meta.json +++ b/static/api/platform-meta.json @@ -1,5 +1,5 @@ { - "commit": "07b5edb", - "source_url": "https://github.com/trakrf/platform/commit/07b5edb0f593eb04bb0a1d22c8a0c3fc2a94fec0", - "spec_refreshed_at": "2026-05-16T11:36:28Z" + "commit": "24db422", + "source_url": "https://github.com/trakrf/platform/commit/24db422ef313cf6c65de118aaebe090d5f922fbc", + "spec_refreshed_at": "2026-05-16T12:53:03Z" }