Developing User Friendly Documentation for FHIR API
| Primary Mentor | Christina White |
| Backup Mentor | The FHIR Squad |
| Assigned to | TBD |
Primary Objective
Develop the OpenMRS Swagger-based FHIR API documentation to add guidance on use of the API.
Project Description
The OpenMRS FHIR API is one of the key mechanisms for developers to access data from OpenMRS. We would like to use Swagger to create auto-generated documentation of the API.
Users of the documentation struggle to understand how to use the FHIR API, making use of the FHIR module harder than necessary. Our auto-generated Swagger documentation provides nice scaffolding for documentation, but doesn’t provide the context, tips, and easy read that those richer API docs (weaving human documentation alongside swagger-like documentation) provide.
With the help of a documentation expert we hope to establish a well structured page which is easy to follow, such as our OpenMRS REST API, GitHub API documentation, Twitter API documentation, or the Google Maps API documentation. At the conclusion of the project we hope to have a format and approach that could be replicated for all modules on OpenMRS moving forward.
Skills Needed
- Possess knowledge in how to structure user documentation for use by different types of users, not only developers or people with technical know how.
- Experience in software engineering, infrastructure engineering, knowledge of how FHIR API works.
- Comfort with working with GitHub repositories.
Objectives at the end of the Assignment :
- A well structured and easy to use FHIR API documentation that provides guidance to developers beyond the auto-generated content from Swagger.
Related Resources
- REST API documentation: OpenMRS REST API
- Repository for OpenMRS REST API documentation
- Sample Swagger documentation: https://psbrandt.io/openmrs-contrib-apidocs/