Stream: implementers
Topic: Autogenerate documentation for FHIR Implementation
Julien Dub (Dec 10 2019 at 15:25):
Hi everyone,
I work with my team at AP-HP (40 french university hospitals) on a FHIR implementation (based on HAPI-FHIR), and we are currently wondering how we should implement an API documentation for it (automatically generated). First we looked at FHIR implementation-guide, which seems a good idea, except it seems more adapted to document how to implement a fhir server, not how it is implemented. We would like to generate a documentation based on a description of what we implemented (described in a yaml/json/xml file) instead of generating a snapshot from a differential, we don't have a differential, we only have a list of what has been implemented...
Is it recommended to use implementation guide for this, should we implement our own documentation, is there any other ways to generate this documentation?
Thank you very much.
Lloyd McKenzie (Dec 10 2019 at 15:43):
To expose exactly what's been implemented (as of a particular time), you can just expose CapabilityStatement and point to profiles from that. However, if you're wanting to publish human-readable documentation, ImplementationGuide is the appropriate vehicle. If you're describing exactly what data you accept/produce, then profiling is the appropriate way. You definitely have a differential because you're expressing the 'delta' between what the base specification allows to be sent/consumed and what your system actually does.
Julien Dub (Dec 10 2019 at 15:54):
Our goal is indeed to publish a human readable documentation, so yes we will probably use ImplementationGuide.
What do you mean by profiling?
We theoritically have a differential, but practically, we don't, and don't know how to generate a differential, that's the problem.
From what I've seen, there is an operation (not sure what an operation is exactly, but it looks like an url on which you provide data and it returns a result): http://hl7.org/fhir/structuredefinition-operation-snapshot.html In this case you give it a differential and it returns the snapshot? What about an url that takes a "capabilitystatement" and returns a differential? It doesn't seem to exist? Is there any way to compute this differential easily?
Thanks you again :)
Julien Dub (Dec 10 2019 at 16:04):
If you want to see the whole picture:
A- We have a file called implemented-fields.yaml in which we defined what is implemented
B- We have a test suite that launches our FHIR implementation, reads the implemented-fields.yaml, and run tests based on what is specified in this file on our running implementation.
C- If all tests passed, we would like to generate our documentation based on this implemented-fields.yaml file
This way we have an implementation and a documentation that matches exactly what we defined in the implemented-fields.yaml file.
This process runs inside a Continuous Integration pipeline everytime someone contribute to our implementation codebase.
This file looks like this, for example with Patient resource: https://gist.github.com/Dubrzr/e6d1483bba0ea65cfe94a831d7af3ae0
It's probably possible to develop something that compares the patient profile with this file and generates a differential but if some higher-level interface/already developped algorithm exists it's very interresting for us!
Thank you :)
Lloyd McKenzie (Dec 10 2019 at 16:22):
The differential would express whatever the changes are between what you're exposing and what you allow. So if you always expose Patient.name, the differential would tighten the "min" to 1. If you treat inclusion of Patient.deceased[x] as an error, then you'd constrain the 'max' to 0. If you want to express your system capabilities in a standardized way, you'll need to find a way to take what's in your yaml file together with the FHIR definitions to determine the differential. I'm not aware of anything pre-existing in this space.
Grahame Grieve (Dec 10 2019 at 20:01):
I am not aware of any coding the generates a differential from a snapshot. But honestly, what you posted looks like a differential to me
Last updated: Apr 12 2022 at 19:14 UTC
