This repository houses the public facing API documentation for Cerner's implementation of the HL7® FHIR® standard, also known as Cerner's Ignite APIs.
The deployed documentation can be viewed at https://fhir.cerner.com/.
Bug reports or notes of areas where documentation is unclear are welcome as repository issues.
Install dependencies with bundler.
$ bundle install
Compile the site with nanoc.
$ bundle exec nanoc
Start up a local web server with nanoc.
$ bundle exec nanoc view
Navigate to http://localhost:3000/ to view the site. When making changes to the site, repeat the last two steps to recompile and view the new content.
We've added attributes at the top of some markdown files to assign a layout. These are usually only needed for pages that aren't actual API documentation (our compilation rule uses that layout attribute before falling back to the api layout).
Layouts themselves are defined in the layouts directory. Some layouts (like the API or FAQ layouts) are used as page templates as mentioned above. Other layouts (like resource category layouts or header/footer layouts) are used to include content in other pages.
There are preprocessing rules that use folder matching to add version and solution attributes to all markdown files for the API. The only thing you need to do to make this work is put resource documentation in /[solution]/[version]/ folder path.
The version and solution attributes are currently used to flex CSS classes, page links, and navigation toolbars/sidebars for the API documentation.
Create and Update operations typically require JSON bodies which can be tedious to document manually through markdown. To simplify this process and to improve consistency we have added the definition_table helper to generate a table from a yaml content file.
The definition_table helper requires 3 parameters: content, action, and version.
content indicates which content file to load.version indicates the version of the content file.action indicates which action specific variations defined in the content file to reflect in the generated table. Typically the action will be :create or :update. The available actions are defined in the content files themselves.Generating a field table is done by invoking the definition_table method through an ERB call in whichever documentation file needs the table.
For example, the DSTU2 version of DocumentReference Create can be generated using:
<%= definition_table(:document_reference, :create, :dstu2) %>
Whereas other versions of AllergyIntolerance Update can be generated (assuming appropriate definitions are available) using:
<%= definition_table(:allergy_intolerance, :update, :r4) %>
In actuality, the version parameter references a subfolder in lib/resources where the content files for that version are stored. Thus definition_table(:document_reference, :create, :dstu2) is referencing lib/resources/dstu2/document_reference.yaml. Adding new versions or new content files is simply a matter of creating an appropriately named folder and content file.
definition_table reads these fields from the resource's content yaml definition:
The terminolgy_table helper is available to generate a terminology binding table from the same yaml content file as definition_table.
The terminolgy_table helper requires 2 parameters: content and version.
content indicates which content file to load.version indicates the version of the content file.Generating a terminology table is done by invoking the terminology_table method through an ERB call in whichever documentation file needs the table.
For example, the DSTU2 version of AllergyIntolerance can be generated using:
<%= terminology_table(:allergy_intolerance, :dstu2) %>
The version parameter processing is handled the same as definition_table.
terminology_table reads these fields from the resource's content yaml definition:
The content is defined in YAML files and most fields are optional. If they are not provided, the resulting table cell will just be empty.
definition_table will generate nested links for each field prepended with this url.field_name_base_url.lib/resources//types.yaml , this field will be linked to the specified resource.tags to preserve formatting.
fields list.field_name_base_url generated URL if defined.Standard YAML formatting rules apply.
In addition to the fields above, each field can have an action field which indicates to which action or actions the field applies. When defined, the field will only be included when generating a table with the specified action. Multiple actions are supported as well and can be defined as a list:
Make the field apply to a single action
- name: subject
...
action: create
Make the field apply to multiple actions
- name: subject
...
action:
- create
- update
Similarly, field values can be flexed per action as well:
Alter the required and note values for update and create
- name: id
required:
- update: 'Yes'
- create: 'No'
type: id
description: The logical id of the resource to update.
example: |
{
"id": "123412"
}
note:
- update: The id value must match the AllergyIntolerance/ value.
- create: The id field must not be set when performing an update operation.
The name of the action isn't limited to create and update, but only one action can be used at a time when generating a field table.
Linking is supported in a few forms.
The field names will be automatically linked based on the base_field_name_url unless overridden by a field's url value.
The Type table cell will generate links based on URLs key-value pairs defined in lib/resources/. Any word found in a type field will be replaced with the specified URL.
The description and note fields also support linking via the use of `` and [] tags. Words enclosed in `` tags will be linked according to the types.yaml file, if possible, or just formatted as tags if not. Words enclosed in [] will be assumed to be references to other fields in the same table.
In general, it is best to not use `` tags in the type field, although it is possible. There can be conflicts which may result in duplicate replacements and unintended results.
