diff --git a/Makefile b/Makefile index 359126ab..d90d08d1 100644 --- a/Makefile +++ b/Makefile @@ -47,6 +47,11 @@ publish: clean mkdir -p build npm run publish 2> /dev/null +#Builds NHS-styled HTML documentation using RapiDoc (matches digital.nhs.uk layout) and opens it +localdev-preview-spec: + poetry run python scripts/localdev_build_spec_for_preview.py + open build/docs.html + #Runs build proxy script build-proxy: scripts/build_proxy.sh diff --git a/scripts/localdev_build_spec_for_preview.py b/scripts/localdev_build_spec_for_preview.py new file mode 100644 index 00000000..642183d7 --- /dev/null +++ b/scripts/localdev_build_spec_for_preview.py @@ -0,0 +1,507 @@ +#!/usr/bin/env python3 +"""Build NHS-styled API documentation using RapiDoc, matching digital.nhs.uk layout.""" + +import os +import re +import subprocess +import sys + +ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +SPEC_FILE = os.path.join(ROOT, "specification", "validated-relationships-service-api.yaml") +BUILD_DIR = os.path.join(ROOT, "build") +BUNDLE_FILE = os.path.join(BUILD_DIR, "spec-bundled.json") +OUTPUT = os.path.join(BUILD_DIR, "docs.html") + +NHS_CATALOGUE_URL = "https://digital.nhs.uk/developer/api-catalogue/validated-relationship-service" + + +def fetch_nhs_js_files(): + """Download NHS Digital's exact rapidoc-min.js and rapidoc-customisation.js using curl.""" + print("Fetching NHS Digital page to find current JS version...") + result = subprocess.run( + ["curl", "-s", NHS_CATALOGUE_URL], + capture_output=True, + text=True, + ) + match = re.search(r"/webfiles/(\d+)/apispecification/rapidoc-min\.js", result.stdout) + if not match: + sys.exit("Could not find rapidoc JS URL on NHS Digital page") + version = match.group(1) + + version_marker = os.path.join(BUILD_DIR, ".js_version") + if os.path.exists(version_marker): + with open(version_marker) as f: + cached_version = f.read().strip() + else: + cached_version = "" + + base = f"https://digital.nhs.uk/webfiles/{version}/apispecification" + for filename in ("rapidoc-min.js", "rapidoc-customisation.js"): + dest = os.path.join(BUILD_DIR, filename) + if os.path.exists(dest) and cached_version == version: + print(f" {filename} already up to date (version {version})") + continue + url = f"{base}/{filename}" + print(f" Downloading {url}") + subprocess.run(["curl", "-s", url, "-o", dest], check=True) + + with open(version_marker, "w") as f: + f.write(version) + return version + + +def bundle_spec(): + print("Bundling spec to JSON...") + result = subprocess.run( + [ + "npx", + "--yes", + "@redocly/cli", + "bundle", + SPEC_FILE, + "--output", + BUNDLE_FILE, + "--ext", + "json", + ], + cwd=ROOT, + capture_output=True, + text=True, + ) + if result.returncode != 0: + print("Error bundling spec:\n", result.stderr, file=sys.stderr) + sys.exit(1) + with open(BUNDLE_FILE) as f: + return f.read() + + +def generate_html(spec_json, js_version): + title = "Validated Relationship Service - FHIR API" + + return f""" + + + + + {title} — LOCALDEV PREVIEW + + + + + + + + + + + + + + + +
+
+
+ +
+
+
+ + +
+
+
+

{title}

+
+

+ This is a LOCALDEV PREVIEW of the API documentation for the Validated Relationships Service. + It is intended for use during development to view the API documentation in a format SIMILAR TO the + NHS Digital API catalogue. +

+

+ Although the layout of this preview is not exact, it should provide confidence to developers + that any changes made to the OpenAPI specification will be reflected in the final published spec. +

+
+ +
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+
+ +
+

+ Back to top +

+
+ +
+
+ + + + + + + +""" + + +def main(): + os.makedirs(BUILD_DIR, exist_ok=True) + js_version = fetch_nhs_js_files() + spec_json = bundle_spec() + html = generate_html(spec_json, js_version) + with open(OUTPUT, "w", encoding="utf-8") as f: + f.write(html) + print(f"Built: {OUTPUT}") + + +if __name__ == "__main__": + main() diff --git a/specification/validated-relationships-service-api.yaml b/specification/validated-relationships-service-api.yaml index 448d4b3f..a506a3d8 100644 --- a/specification/validated-relationships-service-api.yaml +++ b/specification/validated-relationships-service-api.yaml @@ -32,6 +32,7 @@ info: ## Related APIs The following APIs are related to this API: + - [NHS Notify API](https://digital.nhs.uk/developer/api-catalogue/nhs-notify) - we use NHS Notify to send communications to patients, proxies and GPs about their use of this service. - [Personal Demographics Service - FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir) - we use the data held in PDS as a source of data to verify relationships. - [Related Person Network - FHIR API](https://digital.nhs.uk/developer/api-catalogue/related-person-network---fhir-api) - we use the data held in RPN as a source of data to verify relationships.