OAS Generation Tool

The OAS Generation Tool is part of the Digital Tooling commissioned by Health New Zealand | Te Whatu Ora. This is an open-source tool, available in GitHub. Add the package dependency, see the package registry for available releases.

note: the uri below is not where the dependency is resolved from, this is metadata for Implementation Guide documentation. When resolving dependencies, _genonce.sh uses https://simplifier.net/packages, then https://packages2.fhir.org/packages, then local.

dependencies:
  fhir.org.nz.ig.base: 
    uri: http://fhir.org.nz/ig/base
    version: current
  tewhatuora.digitaltooling:
    uri: https://fhir-ig.digital.health.nz/hnz-digital-tooling
    version: 0.0.11

Update the CapabilityStatement definition to use the HnzTooling, and apply the required properties.

note: description maps to Title in the generated OAS.

Instance: PatientSummaryCapabilityStatement
InstanceOf: HnzToolingCapabilityStatement
Usage: #definition

* name = "PatientSummaryCapabilityStatement"
* title = "Patient Summary"
* description = "Patient Summary Operations"

...

// Required by HnzToolingCapabilityStatement
* version = "1.1.0"

* contact.name = "Example Contact Details"
* contact.telecom.value = "https://example.com"
* contact.telecom.system = #url

* extension[HnzApiSpecBuilderExtension].extension[globalHeaders].extension[+].url = Canonical(HnzCustomHeadersExtension)
* extension[HnzApiSpecBuilderExtension].extension[globalHeaders].extension[=].extension[key].valueString = "Correlation-Id"
* extension[HnzApiSpecBuilderExtension].extension[globalHeaders].extension[=].extension[value].valueUri = "https://raw.githubusercontent.com/tewhatuora/schemas/main/fhir-definitions-oas/uuid-definition.json"
* extension[HnzApiSpecBuilderExtension].extension[globalHeaders].extension[=].extension[required].valueBoolean = true
* extension[HnzApiSpecBuilderExtension].extension[licenseURL].valueUri = "https://example.license.org"
* extension[HnzApiSpecBuilderExtension].extension[licenseName].valueString = "GPLv3"
* extension[HnzApiSpecBuilderExtension].extension[externalDocs].valueUri = "https://docs.example.com/fhir"
// end of HnzToolingCapabilityStatement requirements

See the Digital Tooling guide for additional options.

Download the conversion script

mkdir -p ~/fhir-openapi-converter
curl -L -o ~/fhir-openapi-converter/fhir-openapi-converter.js $(curl -s https://api.github.com/repos/tewhatuora/fhir-openapi-converter/releases/latest | jq -r '.assets[] | select(.name == "cli.js") | .browser_download_url')

Run and copy the output to the Implementation Guide

./_genonce.sh && \
LOG_LEVEL=debug node ~/fhir-openapi-converter/fhir-openapi-converter.js --inputFolder fsh-generated --outputFolder oas && \
yaml_file=$(echo oas/*.yaml) && cp -f $yaml_file ./output/${yaml_file##*/} && \
json_file=$(echo oas/*.json) && cp -f $json_file ./output/${json_file##*/}