From 6f51a74a6fce9db3e0048ac37687353e05353652 Mon Sep 17 00:00:00 2001 From: Hongwei Date: Fri, 13 Nov 2026 00:24:57 +0100 Subject: [PATCH 01/10] test: fail on OBP-API paths below v5.1.0 Scans src, server, Dockerfiles, scripts and the example configs for obp/vX.Y.Z and quoted version literals below v5.1.0; any hit must be listed in BELOW_V510 with a reason. --- server/test/obpApiVersion.test.ts | 159 ++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 server/test/obpApiVersion.test.ts diff --git a/server/test/obpApiVersion.test.ts b/server/test/obpApiVersion.test.ts new file mode 100644 index 0000000..d727e6a --- /dev/null +++ b/server/test/obpApiVersion.test.ts @@ -0,0 +1,159 @@ +// The OBP-API version every API Explorer call uses. +// +// OBP-API deployments can switch off the versions below v5.1.0, so every path the Explorer +// (front end and server) sends to OBP-API must use v5.1.0 or newer. This test reads the sources +// and fails on any `obp/vX.Y.Z` below v5.1.0, and on any quoted version literal such as 'v4.0.0' +// (paths here are built from version constants), unless it is listed in BELOW_V510. + +import { describe, expect, it } from 'vitest' + +// vitest.config.js polyfills node built-ins for the browser, which turns `node:fs` into an empty +// stub, so the real module is taken from the Node runtime (Node 20.16 or newer). +const { readFileSync, readdirSync, statSync } = (process as any).getBuiltinModule('node:fs') + +// The repository root, which vitest runs in. +const ROOT = process.cwd() +const join = (...parts: string[]) => parts.join('/') + +// `file|fragment` -> why that line still names a version below v5.1.0. A line is allowed when it +// is in `file` (relative to the repository root) and contains `fragment`. Empty: every call has a +// v5.1.0 or newer equivalent. +const BELOW_V510: Record = {} + +// Where OBP-API paths and versions are written: the front end, the server, the container and +// script files, and the example configuration at the repository root. +const SOURCE_ROOTS = ['src', 'server', 'Dockerfiles', 'scripts'] +const ROOT_FILES = [ + '.env.example', + '.env-docker.example', + 'dockercompose.yml', + 'ai_env.example', + 'env_ai', + 'index.html', + 'vite.config.mts' +] +const EXTENSIONS = [ + 'ts', + 'mts', + 'js', + 'mjs', + 'cjs', + 'vue', + 'html', + 'sh', + 'yml', + 'yaml', + 'conf', + 'go', + 'env' +] +const SKIP_DIRS = ['node_modules', 'dist', 'dist-server'] +// This file, whose examples name old versions on purpose. +const THIS_FILE = 'server/test/obpApiVersion.test.ts' + +function sourceFiles(dir: string, out: string[] = []): string[] { + let names: string[] + try { + names = readdirSync(dir) + } catch { + return out + } + for (const name of names) { + if (name.startsWith('.') || SKIP_DIRS.includes(name)) continue + const path = join(dir, name) + if (statSync(path).isDirectory()) { + sourceFiles(path, out) + } else if (EXTENSIONS.includes(name.split('.').pop() ?? '') || name.startsWith('Dockerfile')) { + out.push(path) + } + } + return out +} + +function allSourceFiles(): string[] { + const files = SOURCE_ROOTS.flatMap((dir) => sourceFiles(join(ROOT, dir))) + return files.concat(ROOT_FILES.map((name) => join(ROOT, name))) +} + +function isBelowV510(major: string, minor: string, patch: string): boolean { + const [a, b, c] = [Number(major), Number(minor), Number(patch)] + return a !== 5 ? a < 5 : b !== 1 ? b < 1 : c < 0 +} + +// Every `obp/vX.Y.Z` and every version literal ('vX.Y.Z' in quotes, or after `=`) in `line` +// whose version is below v5.1.0, as written. +export function versionsBelowV510(line: string): string[] { + const found: string[] = [] + for (const m of line.matchAll(/obp\/v(\d+)\.(\d+)\.(\d+)(?![\d.])/g)) { + if (isBelowV510(m[1], m[2], m[3])) found.push(m[0]) + } + for (const m of line.matchAll(/(?<=['"`=])v(\d+)\.(\d+)\.(\d+)(?=['"`]|\s|$)/g)) { + if (isBelowV510(m[1], m[2], m[3])) found.push(m[0]) + } + return found +} + +function linesBelowV510(): string[] { + const found: string[] = [] + for (const file of allSourceFiles()) { + const rel = file.slice(ROOT.length + 1) + if (rel === THIS_FILE) continue + let text: string + try { + text = readFileSync(file, 'utf8') + } catch { + continue + } + text.split('\n').forEach((line, i) => { + for (const version of versionsBelowV510(line)) { + const allowed = Object.keys(BELOW_V510).some((key) => { + const [keyFile, fragment] = key.split('|') + return keyFile === rel && line.includes(fragment) + }) + if (!allowed) found.push(`${rel}:${i + 1} ${version}`) + } + }) + } + return found +} + +describe('OBP-API version floor', () => { + it('reads the real sources', () => { + // An empty result below must mean "no old version", not "no files". + expect( + allSourceFiles().filter((f) => f.endsWith('.ts') || f.endsWith('.vue')).length + ).toBeGreaterThan(50) + }) + + it('calls OBP-API on v5.1.0 or newer', () => { + expect(linesBelowV510()).toEqual([]) + }) + + it('lists only call sites that still exist', () => { + // A call that moved to v5.1.0 or newer must also leave BELOW_V510. + const stale = Object.keys(BELOW_V510).filter((key) => { + const [file, fragment] = key.split('|') + try { + return !readFileSync(join(ROOT, file), 'utf8').includes(fragment) + } catch { + return true + } + }) + expect(stale).toEqual([]) + }) + + it('recognises the ways a version below v5.1.0 can be written', () => { + expect(versionsBelowV510('get(`/obp/v4.0.0/x`)')).toEqual(['obp/v4.0.0']) + expect(versionsBelowV510("get('obp/v5.0.0/banks')")).toEqual(['obp/v5.0.0']) + expect(versionsBelowV510('"/obp/v3.1.0/a" and "/obp/v1.2.1/b"')).toEqual([ + 'obp/v3.1.0', + 'obp/v1.2.1' + ]) + expect(versionsBelowV510("export const V4_0_0 = 'v4.0.0'")).toEqual(['v4.0.0']) + expect(versionsBelowV510('VITE_OBP_API_VERSION=v4.0.0')).toEqual(['v4.0.0']) + expect(versionsBelowV510('get(`/obp/v5.1.0/x`)')).toEqual([]) + expect(versionsBelowV510("export const V6_0_0 = 'v6.0.0' // /obp/v7.0.0/root")).toEqual([]) + expect(versionsBelowV510('get(`/obp/dynamic-entity/x`)')).toEqual([]) + expect(versionsBelowV510("doc('OBPv4.0.0-getBanks')")).toEqual([]) + }) +}) From 83adbffff094451b96078a99dbdb6540ffb9c9ab Mon Sep 17 00:00:00 2001 From: Hongwei Date: Fri, 13 Nov 2026 00:24:57 +0100 Subject: [PATCH 02/10] test: list every OBP-API call the Explorer makes obp-api-contract/contract.json records verb, path, source, needles, the version constants each path is built from, and the response fields the code reads, for the 28 fixed calls of the front end and the server. --- obp-api-contract/contract.json | 654 +++++++++++++++++++++++++++++++++ 1 file changed, 654 insertions(+) create mode 100644 obp-api-contract/contract.json diff --git a/obp-api-contract/contract.json b/obp-api-contract/contract.json new file mode 100644 index 0000000..61a1066 --- /dev/null +++ b/obp-api-contract/contract.json @@ -0,0 +1,654 @@ +{ + "about": "Every OBP-API call API Explorer II makes from its own code: verb, path (OBP placeholders in capitals), the source file and the text that makes the call (needles), the version constants the path is built from (version_from), and the response fields the code reads. Not listed: the calls whose path the user picks while browsing the docs (Try It in Preview.vue and the generic /api/get, /api/create, /api/update and /api/delete proxy in server/routes/obp.ts, including the public docs cache), and the gRPC services page. not_calls lists the lines that name an OBP-API path without being one of the calls. server/test/obpApiContract.test.ts checks this list against the source and against snapshot.json, which obp-api-contract/snapshot.py writes from an OBP-API's resource docs.", + "calls": [ + { + "verb": "GET", + "path": "/obp/v5.1.0/ui/suggested-session-timeout", + "source": "src/components/AutoLogout.vue", + "needles": [ + "fetch(`${obpApiHost}/obp/${DEFAULT_OBP_API_VERSION}/ui/suggested-session-timeout`)" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + } + ], + "reads": [ + "timeout_in_seconds" + ], + "note": "Sent by the browser straight to VITE_OBP_API_HOST, without a token and past the Explorer server, so it also needs CORS. Without the field the Explorer logs out after 301 seconds." + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/users/USER_ID/entitlements", + "source": "src/obp/index.ts", + "needles": [ + "export async function getUserEntitlements()", + "`/obp/${OBP_API_VERSION}/users/${userId}/entitlements`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + }, + { + "source": "src/obp/index.ts", + "needle": "export const OBP_API_VERSION = DEFAULT_OBP_API_VERSION" + } + ], + "reads": [ + "list[].role_name", + "list[].bank_id" + ], + "note": "Read by Preview.vue to show which of an endpoint's roles the user holds." + }, + { + "verb": "POST", + "path": "/obp/v5.1.0/users/USER_ID/entitlements", + "source": "src/obp/index.ts", + "needles": [ + "export async function createEntitlement(", + "`/obp/${OBP_API_VERSION}/users/${userId}/entitlements`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + }, + { + "source": "src/obp/index.ts", + "needle": "export const OBP_API_VERSION = DEFAULT_OBP_API_VERSION" + } + ], + "reads": [], + "note": "Preview.vue reads only the code and message of an error answer." + }, + { + "verb": "POST", + "path": "/obp/v5.1.0/my/api-collections", + "source": "src/obp/index.ts", + "needles": [ + "const url = `/obp/${OBP_API_VERSION}/my/api-collections`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + }, + { + "source": "src/obp/index.ts", + "needle": "export const OBP_API_VERSION = DEFAULT_OBP_API_VERSION" + } + ], + "reads": [], + "note": "Creates the Favourites collection; Content.vue does not read the answer." + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/my/api-collections", + "source": "src/obp/index.ts", + "needles": [ + "get(`/obp/${OBP_API_VERSION}/my/api-collections`)" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + }, + { + "source": "src/obp/index.ts", + "needle": "export const OBP_API_VERSION = DEFAULT_OBP_API_VERSION" + } + ], + "reads": [ + "api_collections", + "api_collections[].api_collection_name" + ], + "note": "main.ts checks the list is not empty; SearchNav.vue reads each collection's name." + }, + { + "verb": "POST", + "path": "/obp/v5.1.0/my/api-collections/API_COLLECTION_NAME/api-collection-endpoints", + "source": "src/obp/index.ts", + "needles": [ + "`/obp/${OBP_API_VERSION}/my/api-collections/${default_collection_name}/api-collection-endpoints`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + }, + { + "source": "src/obp/index.ts", + "needle": "export const OBP_API_VERSION = DEFAULT_OBP_API_VERSION" + } + ], + "reads": [], + "note": "Adds an endpoint to Favourites; the answer is not read." + }, + { + "verb": "DELETE", + "path": "/obp/v5.1.0/my/api-collections/API_COLLECTION_NAME/api-collection-endpoints/OPERATION_ID", + "source": "src/obp/index.ts", + "needles": [ + "`/obp/${OBP_API_VERSION}/my/api-collections/${default_collection_name}/api-collection-endpoints/${operation_id}`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + }, + { + "source": "src/obp/index.ts", + "needle": "export const OBP_API_VERSION = DEFAULT_OBP_API_VERSION" + } + ], + "reads": [], + "note": "Sent through /api/delete. Content.vue shows any non-empty answer as an error." + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/my/api-collections/API_COLLECTION_NAME/api-collection-endpoints", + "source": "src/obp/index.ts", + "needles": [ + "`/obp/${OBP_API_VERSION}/my/api-collections/${collectionName}/api-collection-endpoints`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + }, + { + "source": "src/obp/index.ts", + "needle": "export const OBP_API_VERSION = DEFAULT_OBP_API_VERSION" + } + ], + "reads": [ + "api_collection_endpoints[].operation_id" + ], + "note": "Read by main.ts and SearchNav.vue." + }, + { + "verb": "GET", + "path": "/obp/v6.0.0/api-collections/API_COLLECTION_ID/api-collection-endpoints", + "source": "src/obp/index.ts", + "needles": [ + "`obp/${V6_0_0}/api-collections/${collectionId}/api-collection-endpoints`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const V6_0_0 = 'v6.0.0'" + } + ], + "reads": [ + "api_collection_endpoints[].operation_id" + ], + "note": "Read by CollectionView.vue." + }, + { + "verb": "GET", + "path": "/obp/v6.0.0/banks", + "source": "src/obp/index.ts", + "needles": [ + "get(`obp/${V6_0_0}/banks`)" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const V6_0_0 = 'v6.0.0'" + } + ], + "reads": [ + "banks[].bank_id", + "banks[].full_name" + ], + "note": "Read by Menu.vue for the bank selector." + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/api/versions", + "source": "src/obp/api-version.ts", + "needles": [ + "get(`obp/${API_VERSIONS_LIST_API_VERSION}/api/versions`)" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const API_VERSIONS_LIST_API_VERSION = 'v7.0.0'" + } + ], + "reads": [ + "scanned_api_versions[].is_active", + "scanned_api_versions[].api_standard", + "scanned_api_versions[].api_short_version", + "scanned_api_versions[].fully_qualified_version" + ], + "note": "main.ts builds the version menu from is_active and fully_qualified_version; resource-docs.ts loads the docs of each active api_standard + api_short_version." + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/resource-docs/API_VERSION/obp", + "source": "src/obp/resource-docs.ts", + "needles": [ + "`/obp/${RESOURCE_DOCS_API_VERSION}/resource-docs/${apiStandardAndVersion}/obp`", + "`/obp/${RESOURCE_DOCS_API_VERSION}/resource-docs/${apiStandardAndVersion}/obp?content=dynamic`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const RESOURCE_DOCS_API_VERSION = 'v7.0.0'" + } + ], + "reads": [ + "resource_docs", + "resource_docs[].operation_id", + "resource_docs[].summary", + "resource_docs[].description", + "resource_docs[].tags", + "resource_docs[].request_verb", + "resource_docs[].request_url", + "resource_docs[].specified_url", + "resource_docs[].example_request_body", + "resource_docs[].success_response_body", + "resource_docs[].error_response_bodies", + "resource_docs[].connector_methods", + "resource_docs[].roles[].role", + "resource_docs[].roles[].requires_bank_id", + "resource_docs[].implemented_by.version", + "resource_docs[].implemented_by.function" + ], + "undocumented_fields": [ + "resource_docs", + "resource_docs[].operation_id", + "resource_docs[].summary", + "resource_docs[].description", + "resource_docs[].tags", + "resource_docs[].request_verb", + "resource_docs[].request_url", + "resource_docs[].specified_url", + "resource_docs[].example_request_body", + "resource_docs[].success_response_body", + "resource_docs[].error_response_bodies", + "resource_docs[].connector_methods", + "resource_docs[].roles[].role", + "resource_docs[].roles[].requires_bank_id", + "resource_docs[].implemented_by.version", + "resource_docs[].implemented_by.function" + ], + "note": "API_VERSION is each active version from api/versions (OBPv7.0.0, UKv3.1, ...). The fields are read by Preview.vue, Content.vue, SearchNav.vue, CollectionView.vue and resource-docs.ts. OBP-API documents no typed response for its resource docs, so every field the Explorer reads is listed in undocumented_fields; the test fails here once OBP-API documents one of them." + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/domain-apis", + "source": "src/obp/domain-apis.ts", + "needles": [ + "get(`/obp/${RESOURCE_DOCS_API_VERSION}/domain-apis`)" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const RESOURCE_DOCS_API_VERSION = 'v7.0.0'" + } + ], + "reads": [ + "domain_apis[].bank_id", + "domain_apis[].base_path", + "domain_apis[].title", + "domain_apis[].description", + "domain_apis[].url", + "domain_apis[].version", + "domain_apis[].openapi_url" + ], + "note": "Content.vue shows title, description, url, version and openapi_url." + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/banks/BANK_ID/domain-apis/resource-docs", + "source": "src/obp/domain-apis.ts", + "needles": [ + "`/obp/${RESOURCE_DOCS_API_VERSION}/banks/${encodeURIComponent(api.bank_id)}/domain-apis/resource-docs?base_path=${api.base_path}`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const RESOURCE_DOCS_API_VERSION = 'v7.0.0'" + } + ], + "reads": [ + "resource_docs", + "resource_docs[].operation_id", + "resource_docs[].summary", + "resource_docs[].description", + "resource_docs[].tags", + "resource_docs[].request_verb", + "resource_docs[].request_url", + "resource_docs[].specified_url", + "resource_docs[].example_request_body", + "resource_docs[].success_response_body", + "resource_docs[].error_response_bodies", + "resource_docs[].connector_methods", + "resource_docs[].roles[].role", + "resource_docs[].roles[].requires_bank_id", + "resource_docs[].implemented_by.version", + "resource_docs[].implemented_by.function" + ], + "undocumented_fields": [ + "resource_docs", + "resource_docs[].operation_id", + "resource_docs[].summary", + "resource_docs[].description", + "resource_docs[].tags", + "resource_docs[].request_verb", + "resource_docs[].request_url", + "resource_docs[].specified_url", + "resource_docs[].example_request_body", + "resource_docs[].success_response_body", + "resource_docs[].error_response_bodies", + "resource_docs[].connector_methods", + "resource_docs[].roles[].role", + "resource_docs[].roles[].requires_bank_id", + "resource_docs[].implemented_by.version", + "resource_docs[].implemented_by.function" + ], + "note": "Shown like any other version's resource docs. OBP-API documents no typed response for its resource docs, so every field the Explorer reads is listed in undocumented_fields; the test fails here once OBP-API documents one of them." + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/api/glossary", + "source": "src/obp/glossary.ts", + "needles": [ + "get(`obp/${GLOSSARY_API_VERSION}/api/glossary`)" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const GLOSSARY_API_VERSION = 'v5.1.0'" + } + ], + "reads": [ + "glossary_items[].title", + "glossary_items[].description.html" + ], + "note": "Read by GlossaryView.vue, GlossarySearchNav.vue, HelpView.vue and MessageDocsListView.vue." + }, + { + "verb": "GET", + "path": "/obp/v6.0.0/system/connectors", + "source": "src/obp/message-docs.ts", + "needles": [ + "get(`obp/${V6_0_0}/system/connectors`)" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const V6_0_0 = 'v6.0.0'" + } + ], + "reads": [ + "connectors[].connector_name" + ], + "note": "Falls back to a fixed connector list when the call fails." + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/message-docs/CONNECTOR", + "source": "src/obp/message-docs.ts", + "needles": [ + "get(`obp/${OBP_API_VERSION}/message-docs/${item}`)" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + }, + { + "source": "src/obp/index.ts", + "needle": "export const OBP_API_VERSION = DEFAULT_OBP_API_VERSION" + } + ], + "reads": [ + "message_docs[].adapter_implementation.group", + "message_docs[].process", + "message_docs[].description", + "message_docs[].outbound_topic", + "message_docs[].inbound_topic", + "message_docs[].example_outbound_message", + "message_docs[].example_inbound_message", + "message_docs[].requiredFieldInfo", + "message_docs[].dependent_endpoints[].name", + "message_docs[].dependent_endpoints[].version" + ], + "note": "Grouped in message-docs.ts and shown by MessageDocsView.vue." + }, + { + "verb": "GET", + "path": "/obp/v6.0.0/message-docs/CONNECTOR/json-schema", + "source": "src/obp/message-docs.ts", + "needles": [ + "get(`obp/${V6_0_0}/message-docs/${item}/json-schema`)" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const V6_0_0 = 'v6.0.0'" + } + ], + "reads": [ + "definitions", + "properties.messages.items[].process", + "properties.messages.items[].description", + "properties.messages.items[].adapter_implementation.group", + "properties.messages.items[].outbound_schema", + "properties.messages.items[].inbound_schema", + "properties.messages.items[].message_format" + ], + "undocumented_fields": [ + "definitions", + "properties.messages.items[].process", + "properties.messages.items[].description", + "properties.messages.items[].adapter_implementation.group", + "properties.messages.items[].outbound_schema", + "properties.messages.items[].inbound_schema", + "properties.messages.items[].message_format" + ], + "note": "The answer is a JSON Schema document; OBP-API documents no typed response for it." + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/resource-docs/API_VERSION/obp", + "source": "server/routes/status.ts", + "needles": [ + "`/obp/${RESOURCE_DOCS_API_VERSION}/resource-docs/${version}/obp`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const RESOURCE_DOCS_API_VERSION = 'v7.0.0'" + } + ], + "reads": [], + "note": "Status check: API_VERSION is the server's own version (DEFAULT_OBP_API_VERSION); only an error code is looked at." + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/message-docs/CONNECTOR", + "source": "server/routes/status.ts", + "needles": [ + "`/obp/${MESSAGE_DOCS_API_VERSION}/message-docs/${connector}`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const MESSAGE_DOCS_API_VERSION = 'v5.1.0'" + } + ], + "reads": [], + "note": "Status check for each of four fixed connectors; only an error code is looked at." + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/api/versions", + "source": "server/routes/status.ts", + "needles": [ + "`/obp/${API_VERSIONS_LIST_API_VERSION}/api/versions`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const API_VERSIONS_LIST_API_VERSION = 'v7.0.0'" + } + ], + "reads": [], + "note": "Status check; only an error code is looked at." + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/users/current", + "source": "server/routes/status.ts", + "needles": [ + "`/obp/${version}/users/current`", + "const version = obpClientService.getOBPVersion()" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + }, + { + "source": "server/services/OBPClientService.ts", + "needle": "version: DEFAULT_OBP_API_VERSION" + } + ], + "reads": [], + "note": "Status check for a logged-in visitor; only an error code is looked at." + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/well-known", + "source": "server/routes/status.ts", + "needles": [ + "/obp/${V5_1_0}/well-known" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const V5_1_0 = 'v5.1.0'" + } + ], + "reads": [ + "well_known_uris", + "well_known_uris[].provider", + "well_known_uris[].url" + ], + "undocumented_fields": [ + "well_known_uris", + "well_known_uris[].provider", + "well_known_uris[].url" + ], + "note": "OIDC debug page. OBP-API answers with WellKnownUrisJsonV510 (well_known_uris: provider, url; see code/api/v5_1_0/Http4s510.scala getOAuth2ServerWellKnown) but its resource doc shows jwks_uris only, in v5.1.0, v6.0.0 and v7.0.0." + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/users/current", + "source": "server/routes/user.ts", + "needles": [ + "`/obp/${version}/users/current`", + "const version = DEFAULT_OBP_API_VERSION" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + } + ], + "reads": [ + "user_id" + ], + "note": "GET /api/user/current answers with the OBP user_id, or the token's sub when this call fails." + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/well-known", + "source": "server/services/OAuth2ProviderManager.ts", + "needles": [ + "/obp/${V5_1_0}/well-known" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const V5_1_0 = 'v5.1.0'" + } + ], + "reads": [ + "well_known_uris", + "well_known_uris[].provider", + "well_known_uris[].url" + ], + "undocumented_fields": [ + "well_known_uris", + "well_known_uris[].provider", + "well_known_uris[].url" + ], + "note": "The login providers the Explorer offers. OBP-API answers with WellKnownUrisJsonV510 (well_known_uris: provider, url; see code/api/v5_1_0/Http4s510.scala getOAuth2ServerWellKnown) but its resource doc shows jwks_uris only, in v5.1.0, v6.0.0 and v7.0.0." + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/root", + "source": "server/services/ObpReachability.ts", + "needles": [ + "`/obp/${version}/root`" + ], + "version_from": [ + { + "source": "src/shared-constants.ts", + "needle": "export const DEFAULT_OBP_API_VERSION = 'v5.1.0'" + }, + { + "source": "server/services/OBPClientService.ts", + "needle": "version: DEFAULT_OBP_API_VERSION" + } + ], + "reads": [], + "note": "GET /api/ready; status.ts passes obpClientService.getOBPVersion(). Only an error code is looked at." + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/banks/SYS/my/roles/ROLE_NAME", + "source": "server/utils/obpRoleCheck.ts", + "needles": [ + "`${obpApiHost}/obp/v7.0.0/banks/SYS/my/roles/${encodeURIComponent(role)}`" + ], + "reads": [ + "allowed_for_auth_modes" + ], + "note": "Guards the Explorer's own monitoring routes with an OBP Role." + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/consumers/current/identity", + "source": "server/services/OIDCServiceHealth.ts", + "needles": [ + "/obp/v7.0.0/consumers/current/identity" + ], + "reads": [ + "consumer_id", + "consumer_name" + ], + "note": "Names the Consumer of the provider health check's client_credentials token." + } + ], + "not_calls": [ + { + "source": "src/components/Preview.vue", + "needle": "operation.specified_url.replace(/\\/obp\\/v\\d+\\.\\d+\\.\\d+\\//, `/obp/${versionWithoutPrefix}/`)", + "reason": "Try It: the path is the chosen endpoint's documented path in the chosen version." + }, + { + "source": "server/app.ts", + "needle": "'ERROR: Check that OBP API is running and returns providers from /obp/v5.1.0/well-known'", + "reason": "Log message about the well-known call in OAuth2ProviderManager.ts." + } + ] +} From 9921cc45a33320d11aeab5722b0eba6987e1ca66 Mon Sep 17 00:00:00 2001 From: Hongwei Date: Fri, 13 Nov 2026 00:24:57 +0100 Subject: [PATCH 03/10] test: snapshot what OBP-API documents for those calls snapshot.py reads the public resource docs of each version in contract.json and records the operation id and response fields of every call; snapshot.json was taken from k8s.openbankproject.com (OBP-API v7.0.0, 474d4bcc). --- obp-api-contract/snapshot.json | 466 +++++++++++++++++++++++++++++++++ obp-api-contract/snapshot.py | 152 +++++++++++ 2 files changed, 618 insertions(+) create mode 100644 obp-api-contract/snapshot.json create mode 100644 obp-api-contract/snapshot.py diff --git a/obp-api-contract/snapshot.json b/obp-api-contract/snapshot.json new file mode 100644 index 0000000..28ca78f --- /dev/null +++ b/obp-api-contract/snapshot.json @@ -0,0 +1,466 @@ +{ + "about": "Written by obp-api-contract/snapshot.py; do not edit by hand.", + "obp_api": { + "https://k8s.openbankproject.com": { + "version": "v7.0.0", + "git_commit": "474d4bcc554f1d8e9516e12d85be121d92410aa5" + } + }, + "taken_at": "2026-11-12T23:23:32Z", + "endpoints": [ + { + "verb": "GET", + "path": "/obp/v5.1.0/ui/suggested-session-timeout", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv5.1.0-suggestedSessionTimeout", + "documented_path": "/obp/v5.1.0/ui/suggested-session-timeout", + "fields": [ + "timeout_in_seconds" + ] + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/users/USER_ID/entitlements", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv4.0.0-getEntitlements", + "documented_path": "/obp/v5.1.0/users/USER_ID/entitlements", + "fields": [ + "list", + "list[]", + "list[].bank_id", + "list[].entitlement_id", + "list[].role_name", + "list[].user_id" + ] + }, + { + "verb": "POST", + "path": "/obp/v5.1.0/users/USER_ID/entitlements", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv2.0.0-addEntitlement", + "documented_path": "/obp/v5.1.0/users/USER_ID/entitlements", + "fields": [ + "bank_id", + "entitlement_id", + "role_name" + ] + }, + { + "verb": "POST", + "path": "/obp/v5.1.0/my/api-collections", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv4.0.0-createMyApiCollection", + "documented_path": "/obp/v5.1.0/my/api-collections", + "fields": [ + "api_collection_id", + "api_collection_name", + "description", + "is_sharable", + "user_id" + ] + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/my/api-collections", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv4.0.0-getMyApiCollections", + "documented_path": "/obp/v5.1.0/my/api-collections", + "fields": [ + "api_collections", + "api_collections[]", + "api_collections[].api_collection_id", + "api_collections[].api_collection_name", + "api_collections[].description", + "api_collections[].is_sharable", + "api_collections[].user_id" + ] + }, + { + "verb": "POST", + "path": "/obp/v5.1.0/my/api-collections/API_COLLECTION_NAME/api-collection-endpoints", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv4.0.0-createMyApiCollectionEndpoint", + "documented_path": "/obp/v5.1.0/my/api-collections/API_COLLECTION_NAME/api-collection-endpoints", + "fields": [ + "api_collection_endpoint_id", + "api_collection_id", + "operation_id" + ] + }, + { + "verb": "DELETE", + "path": "/obp/v5.1.0/my/api-collections/API_COLLECTION_NAME/api-collection-endpoints/OPERATION_ID", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv4.0.0-deleteMyApiCollectionEndpoint", + "documented_path": "/obp/v5.1.0/my/api-collections/API_COLLECTION_NAME/api-collection-endpoints/OPERATION_ID", + "fields": [ + "value" + ] + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/my/api-collections/API_COLLECTION_NAME/api-collection-endpoints", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv4.0.0-getMyApiCollectionEndpoints", + "documented_path": "/obp/v5.1.0/my/api-collections/API_COLLECTION_NAME/api-collection-endpoints", + "fields": [ + "api_collection_endpoints", + "api_collection_endpoints[]", + "api_collection_endpoints[].api_collection_endpoint_id", + "api_collection_endpoints[].api_collection_id", + "api_collection_endpoints[].operation_id" + ] + }, + { + "verb": "GET", + "path": "/obp/v6.0.0/api-collections/API_COLLECTION_ID/api-collection-endpoints", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv4.0.0-getApiCollectionEndpoints", + "documented_path": "/obp/v6.0.0/api-collections/API_COLLECTION_ID/api-collection-endpoints", + "fields": [ + "api_collection_endpoints", + "api_collection_endpoints[]", + "api_collection_endpoints[].api_collection_endpoint_id", + "api_collection_endpoints[].api_collection_id", + "api_collection_endpoints[].operation_id" + ] + }, + { + "verb": "GET", + "path": "/obp/v6.0.0/banks", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv6.0.0-getBanks", + "documented_path": "/obp/v6.0.0/banks", + "fields": [ + "banks", + "banks[]", + "banks[].attributes", + "banks[].attributes[]", + "banks[].attributes[].name", + "banks[].attributes[].value", + "banks[].bank_code", + "banks[].bank_id", + "banks[].bank_routings", + "banks[].bank_routings[]", + "banks[].bank_routings[].address", + "banks[].bank_routings[].scheme", + "banks[].full_name", + "banks[].logo", + "banks[].website" + ] + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/api/versions", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv6.0.0-getScannedApiVersions", + "documented_path": "/obp/v7.0.0/api/versions", + "fields": [ + "scanned_api_versions", + "scanned_api_versions[]", + "scanned_api_versions[].api_short_version", + "scanned_api_versions[].api_standard", + "scanned_api_versions[].fully_qualified_version", + "scanned_api_versions[].is_active", + "scanned_api_versions[].url_prefix" + ] + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/resource-docs/API_VERSION/obp", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv1.4.0-getResourceDocsObp", + "documented_path": "/obp/v7.0.0/resource-docs/API_VERSION/obp", + "fields": [] + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/domain-apis", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv7.0.0-getPubliclyDiscoverableDomainApisInEverySpace", + "documented_path": "/obp/v7.0.0/domain-apis", + "fields": [ + "domain_apis", + "domain_apis[]", + "domain_apis[].bank_id", + "domain_apis[].base_path", + "domain_apis[].description", + "domain_apis[].openapi_url", + "domain_apis[].title", + "domain_apis[].url", + "domain_apis[].version" + ] + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/banks/BANK_ID/domain-apis/resource-docs", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv7.0.0-getDomainApiResourceDocs", + "documented_path": "/obp/v7.0.0/banks/BANK_ID/domain-apis/resource-docs", + "fields": [] + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/api/glossary", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv3.0.0-getApiGlossary", + "documented_path": "/obp/v5.1.0/api/glossary", + "fields": [ + "glossary_items", + "glossary_items[]", + "glossary_items[].description", + "glossary_items[].description.html", + "glossary_items[].description.markdown", + "glossary_items[].title" + ] + }, + { + "verb": "GET", + "path": "/obp/v6.0.0/system/connectors", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv6.0.0-getConnectors", + "documented_path": "/obp/v6.0.0/system/connectors", + "fields": [ + "connectors", + "connectors[]", + "connectors[].connector_name", + "connectors[].is_available_in_method_routing" + ] + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/message-docs/CONNECTOR", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv2.2.0-getMessageDocs", + "documented_path": "/obp/v5.1.0/message-docs/CONNECTOR", + "fields": [ + "message_docs", + "message_docs[]", + "message_docs[].adapter_implementation", + "message_docs[].adapter_implementation.group", + "message_docs[].adapter_implementation.suggested_order", + "message_docs[].dependent_endpoints", + "message_docs[].dependent_endpoints[]", + "message_docs[].dependent_endpoints[].name", + "message_docs[].dependent_endpoints[].version", + "message_docs[].description", + "message_docs[].example_inbound_message", + "message_docs[].example_inbound_message.jsonString", + "message_docs[].example_outbound_message", + "message_docs[].example_outbound_message.jsonString", + "message_docs[].inboundAvroSchema", + "message_docs[].inboundAvroSchema.jsonString", + "message_docs[].inbound_topic", + "message_docs[].message_format", + "message_docs[].outboundAvroSchema", + "message_docs[].outboundAvroSchema.jsonString", + "message_docs[].outbound_topic", + "message_docs[].process", + "message_docs[].requiredFieldInfo", + "message_docs[].requiredFieldInfo.data.bankId", + "message_docs[].requiredFieldInfo.data.bankId[]" + ] + }, + { + "verb": "GET", + "path": "/obp/v6.0.0/message-docs/CONNECTOR/json-schema", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv6.0.0-getMessageDocsJsonSchema", + "documented_path": "/obp/v6.0.0/message-docs/CONNECTOR/json-schema", + "fields": [] + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/resource-docs/API_VERSION/obp", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv1.4.0-getResourceDocsObp", + "documented_path": "/obp/v7.0.0/resource-docs/API_VERSION/obp", + "fields": [] + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/message-docs/CONNECTOR", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv2.2.0-getMessageDocs", + "documented_path": "/obp/v5.1.0/message-docs/CONNECTOR", + "fields": [ + "message_docs", + "message_docs[]", + "message_docs[].adapter_implementation", + "message_docs[].adapter_implementation.group", + "message_docs[].adapter_implementation.suggested_order", + "message_docs[].dependent_endpoints", + "message_docs[].dependent_endpoints[]", + "message_docs[].dependent_endpoints[].name", + "message_docs[].dependent_endpoints[].version", + "message_docs[].description", + "message_docs[].example_inbound_message", + "message_docs[].example_inbound_message.jsonString", + "message_docs[].example_outbound_message", + "message_docs[].example_outbound_message.jsonString", + "message_docs[].inboundAvroSchema", + "message_docs[].inboundAvroSchema.jsonString", + "message_docs[].inbound_topic", + "message_docs[].message_format", + "message_docs[].outboundAvroSchema", + "message_docs[].outboundAvroSchema.jsonString", + "message_docs[].outbound_topic", + "message_docs[].process", + "message_docs[].requiredFieldInfo", + "message_docs[].requiredFieldInfo.data.bankId", + "message_docs[].requiredFieldInfo.data.bankId[]" + ] + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/api/versions", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv6.0.0-getScannedApiVersions", + "documented_path": "/obp/v7.0.0/api/versions", + "fields": [ + "scanned_api_versions", + "scanned_api_versions[]", + "scanned_api_versions[].api_short_version", + "scanned_api_versions[].api_standard", + "scanned_api_versions[].fully_qualified_version", + "scanned_api_versions[].is_active", + "scanned_api_versions[].url_prefix" + ] + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/users/current", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv3.0.0-getCurrentUser", + "documented_path": "/obp/v5.1.0/users/current", + "fields": [ + "email", + "entitlements", + "entitlements.list", + "entitlements.list[]", + "entitlements.list[].bank_id", + "entitlements.list[].entitlement_id", + "entitlements.list[].role_name", + "provider", + "provider_id", + "user_id", + "username", + "views", + "views.list", + "views.list[]", + "views.list[].account_id", + "views.list[].bank_id", + "views.list[].view_id" + ] + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/well-known", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv5.1.0-getOAuth2ServerWellKnown", + "documented_path": "/obp/v5.1.0/well-known", + "fields": [ + "jwks_uris", + "jwks_uris[]", + "jwks_uris[].jwks_uri" + ] + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/users/current", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv3.0.0-getCurrentUser", + "documented_path": "/obp/v5.1.0/users/current", + "fields": [ + "email", + "entitlements", + "entitlements.list", + "entitlements.list[]", + "entitlements.list[].bank_id", + "entitlements.list[].entitlement_id", + "entitlements.list[].role_name", + "provider", + "provider_id", + "user_id", + "username", + "views", + "views.list", + "views.list[]", + "views.list[].account_id", + "views.list[].bank_id", + "views.list[].view_id" + ] + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/well-known", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv5.1.0-getOAuth2ServerWellKnown", + "documented_path": "/obp/v5.1.0/well-known", + "fields": [ + "jwks_uris", + "jwks_uris[]", + "jwks_uris[].jwks_uri" + ] + }, + { + "verb": "GET", + "path": "/obp/v5.1.0/root", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv5.1.0-root", + "documented_path": "/obp/v5.1.0/root", + "fields": [ + "connector", + "energy_source", + "energy_source.organisation", + "energy_source.organisation_website", + "git_commit", + "hosted_at", + "hosted_at.organisation", + "hosted_at.organisation_website", + "hosted_by", + "hosted_by.email", + "hosted_by.organisation", + "hosted_by.organisation_website", + "hosted_by.phone", + "hostname", + "local_identity_provider", + "resource_docs_requires_role", + "version", + "version_status" + ] + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/banks/SYS/my/roles/ROLE_NAME", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv7.0.0-getMyRole", + "documented_path": "/obp/v7.0.0/banks/BANK_ID/my/roles/ROLE_NAME", + "fields": [ + "allowed_for_auth_modes", + "allowed_for_auth_modes[]", + "bank_id", + "caller", + "caller.application_only", + "caller.consumer_id", + "caller.user_id", + "held_by", + "held_by.consumer", + "held_by.user", + "role_name", + "scopes_required" + ] + }, + { + "verb": "GET", + "path": "/obp/v7.0.0/consumers/current/identity", + "docs_from": "https://k8s.openbankproject.com", + "operation_id": "OBPv7.0.0-getCurrentConsumerIdentity", + "documented_path": "/obp/v7.0.0/consumers/current/identity", + "fields": [ + "consumer_id", + "consumer_name" + ] + } + ] +} diff --git a/obp-api-contract/snapshot.py b/obp-api-contract/snapshot.py new file mode 100644 index 0000000..2cda698 --- /dev/null +++ b/obp-api-contract/snapshot.py @@ -0,0 +1,152 @@ +#!/usr/bin/env python3 +# Copyright (C) 2025-2026 TESOBE GmbH +# SPDX-License-Identifier: AGPL-3.0-or-later +# Licensed under the GNU Affero General Public License v3 or later: see the LICENSE and NOTICE files. +"""Write snapshot.json: what an OBP-API documents for each call in contract.json. + + python3 obp-api-contract/snapshot.py --base https://k8s.openbankproject.com \ + [--fallback https://apisandbox.openbankproject.com] + +For every version used in contract.json it reads /obp/{v}/resource-docs/{v}/obp once, +from --base, or from --fallback when --base does not serve that version (a deployment +that switched it off). It finds the endpoint each call reaches and records its operation +id and every response field path, taken from typed_success_response_body. A call with no +endpoint is recorded as missing, so the contract test fails on it. Needs no credentials; +uses only the standard library. + +Matching: OBP writes placeholders in capitals (BANK_ID) and so are some literal segments +(the transaction request type OPEN_CORRIDOR_PROMISE). A segment matches when it is equal, +when the documented one is in capitals (a placeholder for a value the call fills in), or +when both are in capitals. The documented path with the most equal segments wins. +""" +import argparse +import datetime +import json +import os +import re +import sys +import urllib.error +import urllib.request + +HERE = os.path.dirname(os.path.abspath(__file__)) +PLACEHOLDER = re.compile(r"^[A-Z][A-Z0-9_]*$") + + +def get_json(url): + req = urllib.request.Request(url, headers={"Accept": "application/json"}) + with urllib.request.urlopen(req, timeout=300) as resp: + return json.load(resp) + + +def segments(path): + return [s for s in path.split("?")[0].split("/") if s] + + +def match_score(contract_path, documented_path): + """Number of equal segments, or None when the paths cannot be the same endpoint.""" + a, b = segments(contract_path), segments(documented_path) + if len(a) != len(b): + return None + score = 0 + for x, y in zip(a, b): + if x == y: + score += 1 + elif not PLACEHOLDER.match(y): + return None + return score + + +def schema_fields(schema, prefix=""): + """Every field path in a JSON Schema: `a`, `a.b`, `a.list[]`, `a.list[].c`.""" + out = set() + if not isinstance(schema, dict): + return out + if schema.get("type") == "array" or "items" in schema: + out |= schema_fields(schema.get("items", {}), prefix + "[]") + for name, sub in (schema.get("properties") or {}).items(): + path = f"{prefix}.{name}" if prefix else name + out.add(path) + out |= schema_fields(sub, path) + if isinstance(sub, dict) and (sub.get("type") == "array" or "items" in sub): + out.add(path + "[]") + return out + + +def version_of(path): + return segments(path)[1] + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--base", required=True, help="OBP-API base URL") + ap.add_argument("--fallback", help="OBP-API that still serves the versions --base switched off") + ap.add_argument("--out", default=os.path.join(HERE, "snapshot.json")) + args = ap.parse_args() + base = args.base.rstrip("/") + contract = json.load(open(os.path.join(HERE, "contract.json"))) + calls = contract["calls"] + + fallback = args.fallback.rstrip("/") if args.fallback else None + docs, docs_from = {}, {} + for v in sorted({version_of(c["path"]) for c in calls}): + for host in [base] + ([fallback] if fallback else []): + url = f"{host}/obp/{v}/resource-docs/{v}/obp" + print(f"reading {url}", file=sys.stderr) + try: + docs[v] = get_json(url)["resource_docs"] + docs_from[v] = host + break + except urllib.error.HTTPError as e: + print(f" HTTP {e.code}", file=sys.stderr) + if v not in docs: + sys.exit(f"no OBP-API given serves the resource docs of {v}") + + def about(host): + newest = max((v for v in docs if docs_from[v] == host), + key=lambda v: tuple(int(p) for p in v[1:].split("."))) + root = get_json(f"{host}/obp/{newest}/root") + return {"version": root.get("version"), "git_commit": root.get("git_commit")} + hosts = {h: about(h) for h in sorted(set(docs_from.values()))} + + endpoints = [] + for c in calls: + v = version_of(c["path"]) + scored = [] + for d in docs[v]: + if d["request_verb"] != c["verb"]: + continue + score = match_score(c["path"], d.get("specified_url") or d["request_url"]) + if score is not None: + scored.append((score, d)) + scored.sort(key=lambda sd: -sd[0]) + entry = {"verb": c["verb"], "path": c["path"], "docs_from": docs_from[v]} + if scored and len(scored) > 1 and scored[0][0] == scored[1][0]: + entry["ambiguous"] = sorted(d["operation_id"] for s, d in scored if s == scored[0][0]) + if scored: + d = scored[0][1] + entry.update({ + "operation_id": d["operation_id"], + "documented_path": d.get("specified_url") or d["request_url"], + "fields": sorted(schema_fields(d.get("typed_success_response_body") or {})), + }) + else: + entry["missing"] = True + endpoints.append(entry) + + snapshot = { + "about": "Written by obp-api-contract/snapshot.py; do not edit by hand.", + "obp_api": hosts, + "taken_at": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), + "endpoints": endpoints, + } + with open(args.out, "w") as f: + json.dump(snapshot, f, indent=1, ensure_ascii=False) + f.write("\n") + missing = [e["verb"] + " " + e["path"] for e in endpoints if e.get("missing")] + print(f"wrote {args.out}: {len(endpoints)} calls, {len(missing)} with no endpoint", file=sys.stderr) + for m in missing: + print(f" no endpoint: {m}", file=sys.stderr) + + +if __name__ == "__main__": + main() From 1904327049b86033c98cd794971de6b7d415e47d Mon Sep 17 00:00:00 2001 From: Hongwei Date: Fri, 13 Nov 2026 00:24:57 +0100 Subject: [PATCH 04/10] test: check the OBP-API contract offline server/test/obpApiContract.test.ts checks that every needle and version constant is in its source, that every line building an OBP-API path is listed, that the snapshot matches the contract, and that every call and every field it reads is documented unless recorded as a gap. --- server/test/obpApiContract.test.ts | 182 +++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 server/test/obpApiContract.test.ts diff --git a/server/test/obpApiContract.test.ts b/server/test/obpApiContract.test.ts new file mode 100644 index 0000000..a362d9a --- /dev/null +++ b/server/test/obpApiContract.test.ts @@ -0,0 +1,182 @@ +// The contract between API Explorer II and OBP-API. +// +// obp-api-contract/contract.json lists every OBP-API call the Explorer's own code makes, with the +// response fields the code reads. obp-api-contract/snapshot.json is what an OBP-API documents for +// those calls, written by obp-api-contract/snapshot.py from its resource docs. These tests need no +// server: they check that the list matches the code, and that every call reaches an endpoint +// OBP-API documents, with every field the code reads. Retake the snapshot from a new OBP-API build +// to learn whether that build breaks the Explorer. + +import { describe, expect, it } from 'vitest' + +// vitest.config.js polyfills node built-ins for the browser, which turns `node:fs` into an empty +// stub, so the real module is taken from the Node runtime (Node 20.16 or newer). +const { readFileSync, readdirSync, statSync } = (process as any).getBuiltinModule('node:fs') + +// The repository root, which vitest runs in. +const ROOT = process.cwd() + +interface Needle { + source: string + needle: string +} + +interface Call { + verb: string + path: string + source: string + needles: string[] + version_from?: Needle[] + reads: string[] + undocumented_fields?: string[] + undocumented_endpoint?: string +} + +const load = (name: string) => JSON.parse(readFileSync(`${ROOT}/obp-api-contract/${name}`, 'utf8')) +const contract = load('contract.json') +const calls: Call[] = contract.calls +const notCalls: (Needle & { reason: string })[] = contract.not_calls ?? [] +const read = (file: string): string => readFileSync(`${ROOT}/${file}`, 'utf8') +const key = (call: { verb: string; path: string }) => `${call.verb} ${call.path}` + +// The snapshot entry for a call, or undefined. +const documented = (call: Call, snapshot: any) => + snapshot.endpoints.find((e: any) => key(e) === key(call)) + +// The reads of `call` that `fields` does not document. A read written `a|b` is satisfied by either. +export function undocumentedReads(call: { reads: string[] }, fields: Set): string[] { + return call.reads.filter((r) => !r.split('|').some((f) => fields.has(f))) +} + +// The front end and server code, without tests. +function sourceFiles(dir: string, out: string[] = []): string[] { + for (const name of readdirSync(`${ROOT}/${dir}`) as string[]) { + const path = `${dir}/${name}` + if (name === 'test' || name === 'node_modules') continue + if (statSync(`${ROOT}/${path}`).isDirectory()) { + sourceFiles(path, out) + } else if (/\.(ts|mts|js|vue)$/.test(name) && !/\.(test|spec|d)\.ts$/.test(name)) { + out.push(path) + } + } + return out +} + +// Lines that build an OBP-API path (a string with obp/vX or obp/${...}), skipping comments: +// file relative to the repository root, line number, line. +function obpPathLines(): [string, number, string][] { + const out: [string, number, string][] = [] + for (const file of [...sourceFiles('src'), ...sourceFiles('server')]) { + read(file) + .split('\n') + .forEach((line, i) => { + const code = line.trim() + if (/^(\/\/|\/\*|\*|