Initial Release
Generate an OpenAPI 3.0.3 JSON document from any FHIR R4 server’s /metadata
CapabilityStatement. Built for InterSystems IRIS — pure ObjectScript, zero
external dependencies.
set sc = ##class(FHIROAS.OpenAPI).Generate("https://hapi.fhir.org/baseR4", "/tmp/openapi.json")
write $select(sc: "OK", 1: $system.Status.GetErrorText(sc)), !
Reading CapabilityStatement from https://hapi.fhir.org/baseR4/metadata ...
resourceType: CapabilityStatement
FHIR version: 4.0.1
status: active
Resources declared: 148
Total interactions: 665
Building OpenAPI 3.0.3 document ...
Writing to /tmp/openapi.json ...
Done. Output written to: /tmp/openapi.json
Path count: 486
Resource types: 148
The generator reads the server’s own CapabilityStatement — what it declares it
supports — and maps every resource interaction, search parameter, and system
operation into a valid OpenAPI document ready for Gateway import. Written
entirely in ObjectScript: no Python, no Node.js, no external libraries.
Enterprise FHIR deployments almost always sit behind an API Gateway (Kong,
Apigee, AWS API Gateway, Azure API Management). The Gateway team needs an
OpenAPI specification to configure routing, security, and rate limiting.
Writing that spec by hand — for 150+ FHIR resource types, each with multiple
interactions and search parameters — is not feasible.
This tool automates it: point at a /metadata endpoint, get a Gateway-ready
OpenAPI file.
/metadata endpoint. The tool onlyThe self-test mode (SelfTest()) verifies the generator with a built-in
CapabilityStatement and requires no network at all.
git clone https://github.com/your-org/iris-fhir-openapi.git
cd iris-fhir-openapi
docker compose up -d --build
IRIS starts on http://localhost:52773/csp/sys/UtilHome.csp (_SYSTEM / SYS).
docker compose exec iris iris session IRIS -U USER <<'EOF'
do ##class(FHIROAS.OpenAPI).SelfTest()
halt
EOF
This generates a valid OpenAPI 3.0.3 document from a built-in minimal
CapabilityStatement with Patient and Observation resources.
# Public HAPI test server
docker compose exec iris iris session IRIS -U USER <<'EOF'
set sc = ##class(FHIROAS.OpenAPI).Generate(
"https://hapi.fhir.org/baseR4",
"/tmp/openapi.json",
"https://gateway.example.com/fhir/r4",
"HAPI FHIR R4 API",
"1.0.0")
write $select(sc: "OK", 1: $system.Status.GetErrorText(sc)), !
halt
EOF
docker compose cp iris:/tmp/openapi.json ./openapi.json
docker compose exec iris iris session IRIS < docker/demo.script
Runs self-test first, then attempts HAPI. Network failure on HAPI does not fail
the demo.
Import src/cls with Management Portal → System Explorer → Classes →
Import, or from a terminal:
Do $SYSTEM.OBJ.LoadDir("/src/cls", "ck")
Run any of the entry points below.
Classes are installed in the namespace you import them into. Examples use
USER.
Set sc = ##class(FHIROAS.OpenAPI).Generate(
"http://localhost:52773/fhir/r4",
"/tmp/openapi.json",
"https://gateway.example.com/fhir/r4",
"My FHIR API",
"1.0.0")
USER> do Generate^FHIROAS("http://localhost:52773/fhir/r4","/tmp/openapi.json")
USER> do Generate^FHIROAS("http://localhost:52773/fhir/r4","/tmp/openapi.json","https://public.example.com/fhir/r4")
| Parameter | Required | Description |
|---|---|---|
baseURL |
Yes | FHIR server base URL (trailing /metadata is added automatically) |
outputFile |
Yes | Full filesystem path for the output JSON file |
publicBaseURL |
No | Public-facing URL for the API Gateway (defaults to baseURL) |
title |
No | API title — inferred from CapabilityStatement when empty |
version |
No | API version — defaults to "1.0.0" |
sslConfig |
No | SSL/TLS configuration name for HTTPS endpoints |
zpm "install iris-fhir-openapi"
##class(FHIROAS.OpenAPI).Generate(baseURL, outputFile)
│
▼
FHIROAS.CSReader ──► GET /metadata?_format=json
│ Parsed CapabilityStatement (%DynamicObject)
▼
FHIROAS.OASBuilder ──► iterates rest[0].resource[]
│ ├── FHIROAS.PathMapper interaction → HTTP method + URL
│ ├── FHIROAS.SearchParamMapper FHIR type → OpenAPI schema type
│ └── FHIROAS.SchemaRefs components.schemas
▼
%Stream.FileCharacter ──► writes openapi.json
Design notes:
%DynamicObject)%Net.HttpRequest) support is sufficient./metadata. It neverGenerate always overwrites the| FHIR interaction | HTTP | Path |
|---|---|---|
read |
GET | /{Resource}/{id} |
vread |
GET | /{Resource}/{id}/_history/{vid} |
search-type |
GET | /{Resource} |
create |
POST | /{Resource} |
update |
PUT | /{Resource}/{id} |
delete |
DELETE | /{Resource}/{id} |
patch |
PATCH | /{Resource}/{id} |
history-instance |
GET | /{Resource}/{id}/_history |
history-type |
GET | /{Resource}/_history |
| batch / transaction | POST | / |
| search-system | GET | / |
| history-system | GET | /_history |
All search parameters declared in the CapabilityStatement are mapped to OpenAPI
query parameters:
| FHIR type | OpenAPI schema |
|---|---|
number |
{ "type": "number" } |
string |
{ "type": "string" } |
token |
{ "type": "string" } |
date |
{ "type": "string", "format": "date" } |
reference |
{ "type": "string" } |
uri |
{ "type": "string", "format": "uri" } |
quantity / composite / special |
{ "type": "string" } |
Plus common FHIR parameters automatically added: _id, _lastUpdated,
_format, _count, _include, _revinclude, _sort, _summary, _elements.
The components.schemas section contains a lightweight stub for each resource
type (e.g. Patient, Observation). Stubs are intentionally minimal — a
Gateway needs routing metadata, not a full FHIR profile validator.
create but the endpoint rejects writes, the spec will still includePOST path. Gateway teams should treat the spec as a starting point.$everything, $validate, etc.) are not yetOperationDefinition resources.POST / PUT / PATCH. Gatewaysrc/cls/FHIROAS/PathMapper.cls interaction → HTTP method + URL template
src/cls/FHIROAS/SearchParamMapper.cls FHIR search param type → OpenAPI schema
src/cls/FHIROAS/SchemaRefs.cls components.schemas generator
src/cls/FHIROAS/CSReader.cls HTTP GET /metadata, JSON parser
src/cls/FHIROAS/OASBuilder.cls OAS 3.0.3 document builder
src/cls/FHIROAS/OpenAPI.cls entry point + self-test
src/cls/FHIROAS/Generate.mac terminal routine
Rebuild after editing sources:
docker compose up -d --build
MIT — see https://github.com/foxchengyu/iris-fhir-openapi/blob/main/LICENSE.