FHIR Swagger Document generator and enhancements

nadeeshani · March 3, 2016, 3:17am

Hi, I am P.Nadeeshani, a third year undergraduate at Department of Computer Science and Engineering, University of Moratuwa, Sri Lanka. I would like to take part in GSOC Programme 2016 with a OpenMRS project. I have went through the OpenMRS GSoC Project Proposals for 2016. I am very interested on Proposal:FHIR Swagger Document generator and enhancements.I have some understanding on Swagger and API stuff. @harsha89 Can you please tell me how should I proceed with this project. What tasks should I need to do to get started. Any suggestions are highly appreciated.

harsha89 · March 3, 2016, 7:06am

Great to see that you have interested in this project. First thing would be setting the the OpenMRS development environment and get familiar with it. Fixing couple of bugs will be additional plus points for your proposal. Please use these useful resources.

https://wiki.openmrs.org/display/docs/Getting+Started+as+a+Developer

nadeeshani · March 7, 2016, 3:49am

Thanks for the guidance. I am looking at what you have mentioned.

tharaka · March 9, 2016, 8:43pm

Hi, I have being working with the OpenMRS FHIR module for a quite a while now and I am familiar with Swagger as well. Additionally I am aware of recent changes in FHIR module, as I have being working and watching some of them. My objectives towards this project are as follows.

Find out the recent changes in FHIR specifications. I will go through the specification and will create more tickets to implement those. This way we can easily track what we have and what not.
Use bottom-up approach to integrate swagger document generator. Bottom-up approach is used because we have an API at the moment. @harsha89 what is your opinion about this?
Add and improve testcases to improve the test coverage in the module.
Update the related wikis

This is just an outline of my ideas as a start. I would like to discuss further this with community. @harsha89 @surangak Your guidance is highly appreciated.

harsha89 · March 10, 2016, 12:51pm

@tharaka it’s great to see that you are interested in this project. Feel free to ask any question and clarification you need.

tharaka · March 14, 2016, 2:20am

Hi @harsha89,

I went through the details on the project objectives and I still believe that bottom-up approach is better than the top-down approach. I would like to know your thoughts on this.

harsha89 · March 14, 2016, 6:48am

@tharaka it’s fine to follow any approach to generate the document

shekhar · March 15, 2016, 7:44am

Hi @harsha89 @sashrika

I am Shekhar Reddy pursuing third-year B.Tech from Keshav Memorial Institute of Technology, Hyderabad, India. I have been contributing to OpenMRS for the past 3 months and I am interested in working on this project. I have worked on 5 JIRA tickets till date.

I will come up with a good proposal soon, and is there any specific version of openmrs-core to be used to install the fhir module, since I am using core 1.12 for some reasons.

harsha89 · March 15, 2016, 7:58am

Thank you @shekha for your interest. The current kernel version is 2.0.0-alpha:

github.com

openmrs/openmrs-module-fhir/blob/master/pom.xml#L64


      <url>https://github.com/openmrs/openmrs-module-fhir</url>
    <tag>HEAD</tag>
</scm>


  <modules>
      <module>api</module>
      <module>omod</module>
  </modules>


  <properties>
      <openMRSVersion>2.1.0</openMRSVersion>
      <pholocCommonsVersion>4.3.5</pholocCommonsVersion>
      <slf4jApiVersion>1.6.0</slf4jApiVersion>
      <slf4jLog4j12Version>1.6.0</slf4jLog4j12Version>
      <xmlStreamVersion>1.0-2</xmlStreamVersion>
      <SaxonHEVersion>9.4</SaxonHEVersion>
      <hapiFhirBaseVersion>3.3.0</hapiFhirBaseVersion>
      <hapiFhirStructuresDstuVersion>3.3.0</hapiFhirStructuresDstuVersion>
      <hapiValidationResources>3.3.0</hapiValidationResources>
      <thymeleafVersion>2.1.4.RELEASE</thymeleafVersion>
      <phlocSchematronVersion>2.7.1</phlocSchematronVersion>

rasanjana · March 16, 2016, 3:53am

I’m interested about the project of FHIR Swagger Document generator and enhancements. I have recently did some work with FHIR module and found it very interesting. I also went through the FHIR standard and understood the specification. Also Swagger has become one of most popular API documentation language. As the page suggest I have went through the rest document generator project as well. Swagger community offers several tools and libraries to document the APIs.

I will do some research and find out how we can reuse them. One challenge is to get the all FHIR API details to generate the swagger document out of it. I will be looking for possible ways to do it. Meantime, I’l defiantly have some questions and clarifications. @surangak @harsha89 and @sashrika so I will need help from all you guys and guidance for sure.

harsha89 · March 16, 2016, 11:55am

Thank you for your interest @rasanjana. Please let us know if you need any clarifications.

pascal · March 16, 2016, 5:19pm

I’m not sure if this is relevant, but I recently did this work to improve the Swagger documentation for all the REST resources. If the FHIR module simply adds additional resources using the REST module, then it might make sense to do any documentation improvements directly in the REST module.

tharaka · March 17, 2016, 5:36am

That is good information @pascal. I think this makes the beginning very easy for this project.

harsha89 · March 17, 2016, 6:49am

@pascal thank you for letting it know. We are adding the resources through resources controllers of the hapi fhir library. So we have challenge on getting the API details out. I will look on your work and check how we can adapt it

shekhar · March 17, 2016, 7:10am

A small clarification @harsha89

Do we have a resource controller for each resource separately as swagger supposes, or do we have a main controller(only one) ?

Enhance the existing module to meet recent changes of FHIR specification Could you please provide some insight into it like there are a list of recent changes in specifications and mention the specific tasks to be considered under the objective mentioned.

A series of technical corrections to the specification following extensive review:

Corrections to Extension cardinalities in implementation guides
Corrections in the conformance resources that support the specifications
Correct several erroneous invariants
Various typos, broken links, and fixes in examples

Source FHIR v1.0.2

harsha89 · March 17, 2016, 1:29pm

We have resource controllers for each resource. You can go through the FHIR module and check for more details.

We haven’t fully finalized enhancements, but basically we need to upgrade HAPI FHIR library version and support for more resources

shekhar · March 17, 2016, 3:27pm

Thank you @harsha89 for helping out and will be soon with a good proposal

rasanjana · March 18, 2016, 2:58am

@harsha89 There are tools from swagger which build html documentation from the swagger document and client side code generator from the swagger document. Do you think we will need to try out them as part of this effort? As I went through the code, parameters passed as annotations, we may can use to extract API details when we generate the swagger document?

sashrika · March 18, 2016, 3:53am

Hi every one. Nice to see most of you working and researching on this topic, which will help to make this project a success. I see some people has already sent proposals. Me, @harsha89, @surangak will go through them and give feedback.

Any one please use only this thread to get answer any questions about this project. We are here to help you.

sashrika · March 18, 2016, 8:14am

I will quote few people who has already joined this nice conversation, but the facts i am gonna put here will be useful to anyone who is expecting/already put a proposal on this project.

@tharaka , whether to use bottom up approach or , to use top to bottom approach is not yet defined. I too personally prefer the bottom up approach here. But you could include a small notion about pros and cons comparing this two method in ur proposal.

@shekhar yes project enhancement for FHIR specification is also a objective of this project. You could refer both our FHIR implementation and the FHIR specification and note down changes that you gonna implement in you project.

@rasanjana yes, you can refer the rest document generator project and include anything we can get from it. And also @rasanjana client side code generation is not something focus right now, because as long as you have the swagger file, it is possible to generate the client side code any time. But creating a HTML documentation out of the swagger file will be helpful to any one.