Home Applications iris-fhir-openapi

iris-fhir-openapi

Community Project
This project is maintained by its author and is not officially supported by InterSystems. For technical support, please contact the project developer.
0
0 reviews
0
Awards
3
Views
0
IPM installs
0
Add to bundle
Details
Releases (1)
Reviews
Issues
Generate an OpenAPI 3.0.3 JSON document from any FHIR R4 server'

What's new in this version

Initial Release

iris-fhir-openapi   中文版

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.


Why

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.


Prerequisites

  • Docker (for the containerised setup) or an existing InterSystems IRIS
    2023.1+
    instance.
  • Network access to a FHIR R4 server’s /metadata endpoint. The tool only
    reads metadata — it never touches patient data endpoints.

The self-test mode (SelfTest()) verifies the generator with a built-in
CapabilityStatement and requires no network at all.


Quick start

Docker (recommended)

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).

Self-test (zero network — verifies the pipeline):

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.

Against a real FHIR server:

# 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

Demo script:

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.

Existing IRIS instance

  1. Import src/cls with Management Portal → System Explorer → Classes →
    Import
    , or from a terminal:

    Do $SYSTEM.OBJ.LoadDir("/src/cls", "ck")
    
  2. Run any of the entry points below.

Classes are installed in the namespace you import them into. Examples use USER.


Usage

From ObjectScript

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")

From terminal

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")

Parameters

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

Install via IPM

zpm "install iris-fhir-openapi"

How it works

##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:

  • No Python / Node.js dependency. ObjectScript’s native JSON (%DynamicObject)
    and HTTP (%Net.HttpRequest) support is sufficient.
  • Deterministic, not AI. Every mapping is rule-based: CapabilityStatement
    interaction codes → OpenAPI paths → method + parameters. No model inference.
  • Reads what the server declares. The tool only reads /metadata. It never
    calls patient-data endpoints or inspects internal globals.
  • Overwrite semantics. The second call to Generate always overwrites the
    previous output file. There is no append or merge mode.

What gets generated

Resource interactions

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

System interactions

| batch / transaction | POST | / |
| search-system | GET | / |
| history-system | GET | /_history |

Search parameters

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.

Schemas

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.


Limitations

  • FHIR R4 only. R4B and R5 CapabilityStatements are not yet parsed.
  • OpenAPI 3.0.3 only. 3.1 output is not yet supported.
  • Reads declared capabilities only. If a server’s CapabilityStatement says it
    supports create but the endpoint rejects writes, the spec will still include
    the POST path. Gateway teams should treat the spec as a starting point.
  • Custom FHIR Operations ($everything, $validate, etc.) are not yet
    mapped. Their definitions require resolving OperationDefinition resources.
  • Profiles and Implementation Guides (US Core, IPS, Da Vinci) are not
    expanded in the schema section.
  • No request bodies are generated for POST / PUT / PATCH. Gateway
    routing typically only needs paths and methods.

Development

src/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

License

MIT — see https://github.com/foxchengyu/iris-fhir-openapi/blob/main/LICENSE.

Made with
Install
zpm install iris-fhir-openapi
Version
1.0.020 Nov, 2026
Category
Frameworks
Works with
InterSystems IRISInterSystems IRIS for Health
First published
20 Nov, 2026
Last edited
20 Nov, 2026