FHIR Swagger Document generator and enhancements Next Steps

Tags: #<Tag:0x00007f01bc329eb0> #<Tag:0x00007f01bc329d48>

Hi All,

First of it’s existing to be a GSoC Student under OpenMRS. Thanks goes to all my mentors and community members for selecting me.

I would like to discuss activities need to be done within community bonding period with this post. I have made following progress.

  • Went through the web services module swagger implementation and got familiar with it
  1. Went through the HAPI FHIR library APIs to get the conformance statement

  2. Get more familiar with swagger and fhir

  • Also looked at swagger tools

Clarifications needed

  1. One of major doubt on my mind. I saw the module links not available until I installed the legacy UI module. Where we going to implement the swagger UI? Is it as a module link or app in new reference application? Or do we have more options.

I will continue to go through and familiar with code. I will keep this post to post updates and concerns during the community bonding period.

@harsha89 @sashrika please appreciate your feedbacks.

Thanks you Rasanjana

Welcome to OpenMRS and GSoC!

In my opinion the first step is to generate the JSON document that conforms to the OpenAPI (formerly Swagger) specification. Once this is done you can create a new app in the reference application or an OWA (good example here). I prefer the latter, but it’s up to you and your mentors to decide. See here if you’re interested in generating static API docs.

It would be really great if the FHIR resources were included in the main OpenMRS OpenAPI JSON document, since then they would automatically be available in openmrs.js (or any future auto-generated client library). Also, the existing Swagger UI could then be used to browse the resources and operations.

There may be a good use case for a separate, FHIR-only OpenAPI JSON document. You should discuss this with your mentors.

1 Like

@rasanjana thanks for sharing the progress and concerns.

@pascal thanks for sharing your thoughts. Including FHIR resources in OpenMRS OpenAPI JSON document indeed very handy. @rasanjana please note on this in your TODO list. Any document on how we can add them? I too agree we need to first get swagger out of FHIR APIs. Meanwhile we can decide whether writing a reference application app or OWA.

@pascal What should we promote for module developers to build their front end. With OWA are we going to promote OWA? When going through the existing resources I found that OWA has some added advantages like hot deployments.

Thanks, Harsha

1 Like

If your resources are implemented in the standard way (docs here) and are thus registered with the Rest Webservices module, they will automatically be detected by the SwaggerSpecifiationCreator and added to the JSON document.

This is really a question for @burke and the team who lead our technical direction. If you want my opinion - I prefer the OWA technologies and development workflow :slight_smile:.

If your resources are implemented in the standard way (docs here) and are thus registered with the Rest Webservices module, they will automatically be detected by the SwaggerSpecifiationCreator and added to the JSON document.

Oh then it won’t pick fhir. FHIR uses underline hapi fhir restful representation. :frowning:

I would approach FHIR documentation separately from the custom OpenMRS REST API documentation – i.e., these are two separate, distinct APIs that happen to both be RESTful.

My hopes for RESTful API documentation (applies to both FHIR and REST web services documentation):

  • We standardize on an approach (i.e., both OpenMRS REST API and OpenMRS FHIR API use the same approach/tools). I hope that we aren’t creating documentation of a REST API in different ways for each API.
  • Generate documentation as a build step (not dynamically). I believe the REST API documentation is currently building documentation on the fly, which means the documentation has to be built before being displayed rather than simply displaying static pages instantly.
  • Include actual documentation. Displaying an interactive API is a great and important feature, but we need to include some actual documentation as well. I don’t believe the current REST API documentation includes any actual documentation. I would love to have this documentation pulled directly from the JavaDocs. Even (much) better would be to find a contemporary, actively-supported solution (i.e., good bet for the future) to support markdown in JavaDocs (e.g., does this one meet those criteria?). Putting documentation in the wiki or in some other location separate from the code seems like a recipe for creating unmaintained documentation. If we made documenting in JavaDocs easier (e.g., with MarkDown), then we might get better JavaDoc documentation along with better API documentation. :slight_smile:
  • The documentation should live within the application. As was done with the REST API documentation, users should get the living, interactive FHIR documentation as part of the FHIR module.

Committing on specific client-side technology is a work in progress in the community (we’re planning on some strategy discussions on this soon). For now, suggesting Angular + REST (e.g., in an OWA app) is good bet.

3 Likes

Thanks for the deep insight @burke. It definitely helped us. @rasanjana please note the important points :slight_smile:

Sure @harsha89. Thanks all for your suggestions and feedback. For the first phase I’ll be focusing on generating swagger.

1 Like

Hi Guys,

I read through Open API 2.0 and got familiar with it. @pascal I can follow it right? I saw web services module also using same model.

Apart from that I went through servelets of FHIR Module and found one security issue and we will need to improve the annotation descriptions of FHIR APIs to generate more improved swagger documentation. @harsha89 @sashrika I will fix both of them with my initial pull request when coding begins.

Thank you Rasanjana

@rasanjana it’s no need to wait till coding period to submit a pull request :). We can do improvements for the module. Make sure create JIRAs for them. Open API 2.0 should be fine. Let’s do more search on the Open API and how people use it and the compatibility of it with swagger tools.

As we discussed the security issue need to be addressed and great catch on finding it. But as I saw OpenMRS APIs also perform a validation about the user comes with the request. If I remember correct, if no authentication there will be permission issues. But I’m not sure if it’s fully addressed with underline APIs. Shall we write small blog-post with your your current work?

Thank you @harsha89. Created a ticket in https://issues.openmrs.org/browse/FM-188 and pull request https://github.com/openmrs/openmrs-module-fhir/pull/118 to fix servelet authorization issue. Will look into other places.

Great @rasanjana let’s add module improvements along with tickets and complete the blogpost with your findings on swagger and OpenAPI :slight_smile:

@harsha89 please find blogpost in https://rasanjanacreations.wordpress.com/2016/05/12/experience-with-swagger-and-community-bonding-period-of-gsoc-openmrs/. Let me know it’s fine.

@rasanjana it’s looks good. Let’s add more details with yout progress. It will be good experience as you will need to write blogpost for every week after coding period has begin. Also pull requests for minor bug fixes are always welcome :slight_smile:

Previous week I was able to go through the whole specification and identified where should I start the coding. @harsha89 sorry for the delay as me and our friends working on helping people who affected by floods in Sri Lanka. Since coding begins from Monday I believe I’m in good position to complete my first phase of the project with allocated time.

Thanks for the update @rasanjana. Let us know if you need any help on coding. :slight_smile:

Quick question on resource URI expose the swagger documentation of FHIR API. I have added a servelet and a filter mapping /ws/docs/fhir/swagger. Swagger document will be accessible from uri http://localhost:8080/openmrs/ws/docs/fhir/swagger. I hope naming of resource URI is fine. I appreciate any suggestions on this.

For reference, the current REST Module OpenAPI spec is accessed at:

/openmrs/module/webservices/rest/swagger.json

So to be consistent, maybe we should use something like:

/openmrs/module/fhir/rest/swagger.json

What are the URLs of your actual resources?

@pascal thank you for the info. Our resource URLs will be like /openmrs/ws/fhir/Patient. URLs are bit deviate from our rest webservices module. But we can unify the swagger resource URL which will be consistent. @rasanjana let’s change it as @pascal mentioned.

Can you use all lowercase like the REST Module? REST resources also usually include a version:

/openmrs/ws/rest/v1/concept

I don’t know how your module is designed, but does it make sense for you to include that?