FHIR Swagger Documentation

Overview

Swagger Document of FHIR APIs gives comprehensive representation of available FHIR REST APIs of OpenMRS FHIR Module. The swagger document is generated based on OpenAPI specification which is the international accepted specification to build swagger documentation of APIs. Swagger document defines a set of properties required to describe an API. These documents then used by the UI libraries to generate UI representation of swagger document, code generator tools to generate clients in various languages and etc. Additional utilities can also take advantage of the resulting files, such as testing tools. Following are the main parts of the OpenAPI specification.

General information about the API
- General information about API such as who belongs it, licence, contact details
Available paths (/resources)
- This contains all available resources of particular API. If we can take a example of user API, GET by /user/{id} is one resource which we can take details of a particular user and /user will be another resource where people can do POST requests to that endpoint to create users and search users with parameter.
Available operations on each path
- Operations are the GET/DELETE/POST/PUT operations permitted in each of the resource. For example /user endpoint may have GET endpoint to search employees and POST to create users.
Input/Output for each operation
- This section contains what are the inputs needed for the particular operation and output returned from the operation. POST request to /user resource will need user details as json while /user/{id} need input user id to get the details of a particular user.

Figure 1 : Representation of an API defined by OpenAPI

Swagger Documentation

The swagger documentation of FHIR API is available through http://{serverHost}:{serverPort}/openmrs/module/fhir/rest/swagger.json. In local deployment after installing FHIR module it’s available through http://localhost:8080/openmrs/module/fhir/rest/swagger.json. This provides details of all available resources exposed through FHIR API. Document provides supported http methods for each resource, input object formats, output object formats and etc. Here is the full swagger document for the FHIR REST APIs. Figure 2 shows the overview of swagger document. It shows the information section and expanded Encounter resources that shows the available operations.

Figure 2 : Overview of Swagger Document

Figure 3 shows shorted format of json representation which include only a single resource which is encounter resource.

{
 "swagger": "2.0",
 "info": {
   "version": "1.0.0",
   "title": "OpenMRS FHIR REST Services",
   "description": "Auto-generated documentation for OpenMRS FHIR Rest services",
   "termsOfService": "https://www.mozilla.org/en-US/MPL/2.0/",
   "contact": {
     "name": "OpenMRS FHIR Module Team",
     "url": "https://talk.openmrs.org/c/dev",
     "email": "community@openmrs.org"
   },
   "license": {
     "name": "Mozilla Public License, v. 2.0",
     "url": "http://openmrs.org/license/"
   }
 },
 "host": "localhost:8080",
 "basePath": "/openmrs/ws/fhir",
 "consumes": [
   "application/xml",
   "application/json"
 ],
 "produces": [
   "application/json",
   "application/xml",
   "application/xml+fhir",
   "application/json+fhir"
 ],
 "paths": {
   "/Encounter": {
     "post": {
       "summary": "Create Encounter resource from the content of the request",
       "produces": [
         "application/json",
         "application/xml",
         "application/xml+fhir",
         "application/json+fhir"
       ],
       "parameters": [
         {
           "name": "body",
           "in": "body",
           "description": "Encounter resource object",
           "required": true,
           "schema": {
             "$ref": "#/definitions/Encounter"
           }
         }
       ],
       "responses": {
         "200": {
           "description": "Returns success operation outcome",
           "schema": {
             "type": "object",
             "$ref": "#/definitions/OperationOutcome"
           },
           "examples": {
             "application/json": "{\"resourceType\":\"OperationOutcome\",\"issue\":[{\"severity\":\"information\",\"details\":\"Details of operation\"}]}"
           }
         },
         "404": {
           "description": "When error occurred",
           "schema": {
             "type": "object",
             "$ref": "#/definitions/GeneralError"
           },
           "examples": {
             "application/json": "{\"resourceType\":\"OperationOutcome\",\"issue\":[{\"severity\":\"error\",\"details\":\"Details of error\"}]}"
           }
         }
       }
     },
     "get": {
       "summary": "Returns Encounter matching results",
       "produces": [
         "application/json",
         "application/xml",
         "application/xml+fhir",
         "application/json+fhir"
       ],
       "parameters": [
         {
           "name": "patient",
           "in": "query",
           "description": "",
           "required": false,
           "type": "string"
         },
         {
           "name": "part-of",
           "in": "query",
           "description": "",
           "required": false,
           "type": "string"
         },
         {
           "name": "_id",
           "in": "query",
           "description": "The ID of the resource",
           "required": false,
           "type": "string"
         }
       ],
       "responses": {
         "200": {
           "description": "Bundle of Encounter resources",
           "schema": {
             "type": "array",
             "$ref": "#/definitions/Encounter"
           },
           "examples": {
             "application/json": "{\n  \"resourceType\": \"Encounter\",\n  \"status\": \"finished\",\n  \"class\": \"inpatient\",\n  \"subject\": {\n    \"reference\": \"Patient/dd738d54-1691-11df-97a5-7038c432aabf\",\n    \"display\": \"Daisylene Ekeno(Identifier:1865TU-8)\"\n  },\n  \"participant\": [\n    {\n      \"individual\": {\n        \"reference\": \"Practitioner/bf218490-1691-11df-97a5-7038c432aabf\",\n        \"display\": \"Super User(Identifier:admin)\"\n      }\n    }\n  ],\n  \"period\": {\n    \"start\": \"2006-02-07T00:00:00\",\n    \"end\": \"2006-02-07T00:00:00\"\n  },\n  \"location\": [\n    {\n      \"location\": {\n        \"reference\": \"Location/8d6c993e-c2cc-11de-8d13-0010c6dffd0f\",\n        \"display\": \"Inpatient Ward\"\n      },\n      \"period\": {\n        \"start\": \"2006-02-07T00:00:00\",\n        \"end\": \"2006-02-07T00:00:00\"\n      }\n    }\n  ]\n}"
           }
         },
         "404": {
           "description": "When error occurred",
           "schema": {
             "type": "object",
             "$ref": "#/definitions/GeneralError"
           },
           "examples": {
             "application/json": "{\"resourceType\":\"OperationOutcome\",\"issue\":[{\"severity\":\"error\",\"details\":\"Details of error\"}]}"
           }
         }
       }
     }
   }
 },
 "definitions": {
   "Condition": {
     "type": "object"
   },
   "Bundle": {
     "type": "object"
   },
   "DiagnosticReport": {
     "type": "object"
   },
   "Patient": {
     "type": "object"
   },
   "Practitioner": {
     "type": "object"
   },
   "AllergyIntolerance": {
     "type": "object"
   },
   "FamilyMemberHistory": {
     "type": "object"
   },
   "OperationOutcome": {
     "type": "object"
   },
   "Observation": {
     "type": "object"
   },
   "Encounter": {
     "type": "object"
   },
   "Person": {
     "type": "object"
   },
   "GeneralError": {
     "type": "object"
   },
   "Location": {
     "type": "object"
   }
 },
 "externalDocs": {
   "description": "Find more info here",
   "url": "https://wiki.openmrs.org/display/projects/OpenMRS+FHIR+Module"
 },
 "parameters": {
   "formatParam": {
     "name": "_format",
     "in": "query",
     "description": "Format parameter can use to get response by setting _fromat param value  from xml by _format=xml and response from json by _format=json",
     "required": false,
     "type": "string"
   }
 }
}

Figure 3 : Swagger Document JSON Representation

UI Representation

The FHIR module comes with a rich UI to represent the FHIR REST API swagger documentation which built using swagger UI library. User can navigate to Administration view of the OpenMRS UI and then click on Swagger Documentation link under the FHIR Module links as in Figure 4.

Figure 4 : FHIR Module Swagger Documentation Link

Figure 5 shows the Swagger Document UI representation. It listed operations of all available resources based on HTTP Method such as GET, PUT, POST, DELETE and HEAD. This is located at http://{serverHost}:{serverPort}/openmrs/module/fhir/apidocs.form#/default location. For local installations, user can view this through accessing http://localhost:8080/openmrs/module/fhir/apidocs.form#/default URL.

Figure 5 : UI Representation of Swagger Document

Figure 6 shows the expanded view of GET operation of Location resource. It shows query parameters supported the operation and description of each query parameter and the success response format. Likewise each operation contains comprehensive set of details which can be used as a full representation of a API. Figure 7 shows the expanded view of Location POST operation which indicate the properties of Location creation request.

Figure 6 : Expanded Location Resource GET Operation

Figure 7 : Expanded Location Resource POST Operation

API Invocation

Swagger UI implementation support testing the API through the UI itself. By filling appropriate values in query parameter in GET operation or body parameter in POST operation, user can invoke an API. Figure 7 shows invocation result of GET Patient by UUID.

Figure 7 : Invocation of Get Patient By UUID Operation

Summary

The swagger representation of an API is very powerful resource to get the full details of a API. Swagger document of FHIR APIs contains all required information required to represent the OpenMRS FHIR API. As discussed above, user can retrieve the swagger document json representation from the swagger document endpoint in http://{serverHost}:{serverPort}/openmrs/module/fhir/rest/swagger.json. Powerful swagger document UI representation allows users to go through all available resources and it’s details very easily and try out the available operations instantly. On other hand swagger document can used to generate clients in any language which can be directly used within applications. Swagger is becoming more and more popular among the community. On the other hand, having FHIR API represent through swagger enhance the understandability of the API for users.

Projects