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.
FHIR Swagger Document generator and enhancements Project Proposal
Introduction
FHIR standard rapidly gets popular among community. Swagger is one of most popular API documentation language. Objective of project is to integrate swagger document generator and improve module to meet recent changes of FHIR Specification. Part of the swagger integration, the required UIs needs to be built on top of new UI framework as legacy UI now has been depreciated. Also during this project it’s required to perform several enhancements for the project like library version upgrade and align the current implementation align with newest version of the library.
Prerequisites
Learn the FHIR standard
Go through the OpenMRS FHIR Module and try out the FHIR module
Objectives
Integrate the swagger documentation generation and console for FHIR REST APIs
Implement the UI of swagger documentation in new UI framework
Perform the module enhancements as requested
Go through the swagger tools and adopt them during the project
Benefits
Exposing FHIR Rest API with swagger enables many users to use FHIR through swagger which is the most popular API popular framework for the APIs, It allows users to identify the details of a particular FHIR API easily and invoke it through the swagger UI and try it out.
Enable using tools provided by swagger community with the FHIR REST API
Enhancing module helps users to interact with latest changes with FHIR standard
Improve module experience
Deliverables
Source code of the swagger integration
Documentation in the OpenMRS wiki page on using swagger with FHIR
Upgrading FHIR library
Approach
With my previous experience of FHIR module I think we need to first figure out to extract the API details from FHIR, When I went through the FHIR standard, noticed that conformance statements gives the all the API details which we can use to build the swagger document.
As requested I further looked at conformance statement. In FHIR specification[1], it specifies that conformance statement return number of data include API details. Under resources section it returns API details. I looked at FHIR module conformance statement and extracted following section for Patient. It’s giving the supported operations and search parameters. I think it will be appropriate. I will continue my research.
{
"type":"Patient",
"profile":{
"reference":"http://hl7.org/fhir/profiles/Patient"
},
"interaction":[
{
"code":"read"
},
{
"code":"update"
},
{
"code":"delete"
},
{
"code":"create"
},
{
"code":"search-type"
}
],
"conditionalUpdate":true,
"searchParam":[
{
"name":"identifier",
"type":"token",
"documentation":"A patient identifier"
},
{
"name":"_id",
"type":"token",
"documentation":"The ID of the resource"
},
{
"name":"family",
"type":"string",
"documentation":"A portion of the family name of the patient"
},
{
"name":"name",
"type":"string",
"documentation":"A portion of either family or given name of the patient"
},
{
"name":"active",
"type":"token",
"documentation":"Whether the patient record is active"
},
{
"name":"given",
"type":"string",
"documentation":"A portion of the given name of the patient"
},
{
"name":"careprovider",
"type":"reference",
"documentation":"Patient's nominated care provider, could be a care manager, not the organization that manages the record"
}
]
},
I proposed following diagram to generate and render the swagger UI.
Image 1 : Implementation overview
I have gone through the REST document generator and the resources provided by Pascal. So we need mapper to generate the swagger document. So I have included the mapper on the above diagram. From mapper we can expose the API to get the swagger document. This API can use in the front end to render the in the swagger UI.
After completing the integration, I will focus on the module enhancements suggested by mentor.
Meanwhile I will go through the existing documentation generator libraries to generate the API documents as used in the REST Document generator project.
Samples
I have worked on went through the swagger UI and the editor and made a sample swagger mock-up for FHIR APIs. The sample swagger json can be found in https://github.com/rasanjanap/Swagger_Samples/blob/master/SampleSwagger.json . When the swagger doc has generated the following UIs will be loaded through the Swagger UI library.
You can test the above URL in http://petstore.swagger.io/#/.
Swagger editor rendering the sample json. We might can integrate the editor if needed.
Resources
Project Timeline
22 April 2016 - 23 May 2016
During the community bonding period my plan is to learn on swagger into more depth and finding the usage of the tools provided by the swagger community and how they can adopt into this project.
Also I will go through the FHIR specification and identify any new things that can be integrated with the current module functionality. Also I will research on how we can obtained the full API details to the mapper
23 May 2016 - 30 May 2016
Starting implementing the API to get the all API details to the mapper and start the basic structure of the FHIR API details to swagger document mapper
30 May 2016 - 6 Jun 2016
Go through the format of the API details returns from the FHIR API details and start mapping the basic HTTP Operations such as GET, POST, PUT and DELETE to the swagger document generator
6 Jun 2016 - 13 Jun 2016
Start mapping search parameters and other relevant attributes to the FHIR API details to Swagger document generator mapper
13 Jun 2016 - 20 Jun 2016
Testing and finalize the mapper and obtain the swagger document through the API
20 Jun 2016 - 27 Jun 2016
During the midterm evaluations, I will work on the swagger UI integration to the front end to generate the swagger UI from the swagger document. This week I will do research on integrating it.
27 Jun 2016 - 04 Jul 2016
Start implementation of swagger UI integration and make the basic functionality to work
04 Jul 2016 - 11 Jul 2016
Finalize the swagger document generator and start looking at the required enhancements of the FHIR module
11 Jul 2016 - 18 Jul 2016
Working on FHIR enhancements like hapi fhir upgrade and required changes for the FHIR resources
18 Jul 2016 - 25 Jul 2016
Continue to work on enhancements and integration of swagger tools to the current implementation
25 Jul 2016 - 1 Aug 2016
Continue to work on enhancements and integration of swagger tools to the current implementation
1 Aug 2016 - 8 Aug 2016
Discuss with mentor and finalized and perform necessary minor improvements to the work carried out during the project timeline
8 Aug 2016 - 15 Aug 2016
Completing documentation on the swagger document generator and the module enhancements carried out during this implementation
Profile Information
Who are you? What are you studying?
I’m Kavinda Rasanjana Perera, A undergraduate of Sri Lanka Institute of Information Technology(SLIIT). I’m following undergraduate degree program in bachelor of information technology stream.
Why are you the right person for this task?
I have got to know about the GSoC from a program hosted in SLIIT. Then I searched through internet and find out more information about the program. Couple of my friends gave me introduction about the open source projects. Eventhough some libraries that used in my projects are coming from open source projects, I didn’t noticed it. I feel I need to make contributions to open source projects. While I’m searching for projects, I found OpenMRS through a post that shared in my facebook timeline which is from my friend. So I started contributing to OpenMRS beginning of this year. I had worked on couple of core tickets and many FHIR module tickets. I had learned lot through this shortened period of time. Spring. Hibernate is the key things that I have learned. Since I have worked more on the FHIR module, I have better understanding about the project and it’s structure. I found swagger document generator project interesting due to my background of this project and the interest on learning the swagger. Due to module understanding and willingness to learn the swagger made me confident of this project. I’m also a member of FOSS community at SLIIT.
Describe in detail your software development experience by various technologies. Include all technologies you have used for development projects.
During my degree program I have developed several projects under different set of technologies. Following are the projects that I have developed and the details along with the technologies.
Oleada-Online Music Store
Developed a website using C# language that helps users to search and buy original music albums. This system allows users to do following functions:
1. User account management
2. Search albums
3. Add albums into the cart
4. Order albums and view the history of the orders
Tools and Technologies:
Visual Studio 2010
SQL Server 2008
HTML5
CSS
Automated System for Travel Agency (Group Project)
Developed automated travel agency application using Java that helps travel agents to manage all the details of their travel agency according to their preferences. This system has following capabilities
1. Create a user account.
2. Search a Vehicle/Travel Officer/Travel Guide
3. Select and assign Vehicle/Travel Officer/Travel Guide
4. Make Reservations
Tools and Technologies:
Java
Netbeans
MySQL
Jasper Report
Inventory Control and Payroll System (Group Project)
Developed An Inventory Control and Payroll System for a company called JI Air Conditioning systems using Java that allows users to manage all the manual processes and details digitally and efficiently by using this system. It allows users to manage following functions and generate required reports.
1. User Management details (Introduced barcoded ID card)
2. Inventory management
3. Service management
4. Vehicle management
5. Employee management
6. Customer management
Tools and Technologies:
Java
Netbeans
MySQL
Jasper Report
JCB Calculator Android Application
Developed JCB Calculator android applications that helps users to keep records and do calculations easily . This application has following functions.
Keep track of the meter
Calculate fees
Save and view records
Send messages to owner
Tools and Technologies:
Java
Android
Eclipse
SQLite
Eagle Eye – Face Recognition System For CCTV
The Eagle Eye, A Face Detection and Recognition System which provide the facility to face detection and recognition on live CCTV video. This system is done using Java programming language using OpenCV image processing techniques and algorithms. The system can detect, recognize and compare faces in real time manner in a live video. The automatic profiling algorithms implement of profile frequent person and store detail for future references.
1. Detect faces
2. Recognize faces
3. Compare the detected face with already profiled faces.
4. Create triggers to specific person and get alerts
Tools and Technologies:
Java
Netbeans
MySQL
OpenCV
List any previous experience working with open source projects other than OpenMRS.
I have used OpenCV on Eagle Eye, A Face Recognition System For CCTV research project.
I have used Apache Cordova which is an open source mobile application framework from Apache to develop cross platform mobile applications
Provide links to any websites or applications created by you, or other source code examples.
Source code of a java desktop application project mentioned in above named Automated System for Travel Agency
Android application which targeted on small kids to provide simple maths quizzes and check their answers
https://github.com/rasanjanap/Inventory-Control-and-Payroll-System
Source code of a java desktop application project mentioned in above named Inventory Control and Payroll System
Source code of a java desktop application project mentioned in above named Eagle Eye – Face Recognition System For CCTV
My github account
My stackoverflow account
Please provide the URL to your wiki personal space and OpenMRS Talk profile page.
OpenMRS talk : https://talk.openmrs.org/users/rasanjana/activity
OpenMRS wiki : https://wiki.openmrs.org/display/~rasanjana
You must have made at least one coding contribution to OpenMRS BEFORE submitting your proposal.
Worked on it at identified that it’s already fixed
Describe your interactions with our community so far. Include dates of developer forums you have attended, and include any IRC nicknames used when visiting our channel previously.
Please find my interactions on topics of OpenMRS talk
https://talk.openmrs.org/t/openmrs-sso-capabilities/4630 This is about getting know of the SSO capabilities of OpenMRS. It was a good conversation
https://talk.openmrs.org/t/ideas-from-potential-students-for-gsoc-2016-projects/4628/12 This post I have suggest some GSoC Ideas
https://talk.openmrs.org/t/fhir-appointment-mapping-issue-against-openmrs-appointment-module/4896 Discussion on issues encounter when developing the FHIR appointment mapper
What is your preferred method of contact and how should we reach you with it? (phone, email, IRC, IM, etc.)
Phone : 0772776778`
IM : krasanjana93, kavinda.rasanjana
Telegram : Kavinda Rasanjana
Email : krasanjana93@gmail.com, kavinda.rasanjana@gmail.com
Do you have any other commitments during the program? (Include any and all holidays, vacations, travel, exams, classes, research projects, other work, job offers, etc.)
I have semester exams starting from 18th of April upto two weeks in duration. Other than that I don’t have any other commitments.