Please take a look at how we’ve documented the resource, with mappings to the OpenMRS location object, and defined a set of search / query actions that the OpenMRS FHIR module currently supports. The table is not complete (I did some edits) but you get the general idea…
Would appreciate any feedback on what you think of this page, and wether it should be used as a template of sorts
In addition, will the community benefit from adding working curl requests for each operation into the wiki page?
@sashrika put great effort to start on documenting the fhir resources. We though this is a much needed thing because having a API not enough to users to understand what each API does without a proper documentation of a API. Indeed we can improve this with the resource changes.
I think if we provide the correct syntax of the supported APIs, curl request are pretty straight forward for get requests. But when it come to POST, UPDATE we may need to provide samples.
@surangak we have included json representation of the object. shall we include both JSON and XML representations in two tabs?
With the help of @surangak and @harsha89, we were able to do something useful for the FHIR module. Since these resources, URIs and parameters are fairly complex, it is very useful to make a proper documentation of the API. We are in the process of covering all the resources in the FHIR module. So any comments or feedback for improving the usability and quality of the API documentation would be helpful for the both community and devs
In my opinion, documenting resources on the wiki is too far from the code. It can be useful momentarily, but is almost guaranteed not keep up with changes in the module.
A better approach is to create a self-documenting module – i.e., document with javadoc & annotations in the source code and use a tool ± script to auto-generate the documentation that can run as a live, interactive reference available to admins running the module. Anyone looking for the documentation without their own running system could refer to it within the OpenMRS demo server.
What do you think @surangak and @harsha89 ? If we can come up with such mechanism we don’t need to bother about updating the documentation.
But in another point of view once we implement an API for a particular resource, the API itself should not be subjected to frequent changes, because FHIR is a standard specification. We can rely on the fact that these specifications doesn’t change with time. unless we improve the existing API by adding more search parameters and like that.
One drawback I see in self-documenting module with javadoc&annotations for the FHIR module is, we are not just documenting the API for a particular resource. As an example we document how a FHIR Resource map to the attributes of a OpenMRS object, a sample JSON representation of the FHIR resource. I am not sure whether it is possible to add such details to a auto generated document.
When I speak of a script to auto-generate the documentation, I am not suggesting a solution without manually written documentation; rather, I’m suggesting that the manual documentation be done within the code (e.g., in javadoc) so any form of documentation resource (wiki pages, Swagger-like interactive documentation in the module, etc.) could be generated via script (e.g., maven) from the source code.
To facilitate decent (more comprehensive) documentation within javadoc comments, it would be great if there were a widely used markdown doclet we could adopt. markdown-doclet is in google code (closing in 2016) and pegdown-doclet only has 10 forks & 3 contributors (is it “widely used”?).
@burke agreed that it’s very useful to have a auto generated tool for the APIs.
FHIR uses conformance statement which client can used to know about the supporting APIs. In qa server http://qa01.openmrs.org:8080/openmrs/ws/fhir/metadata will gave the details of all supporting APIs with details of each API which is supported by the underline HAPI library. We also can alter the return Conformance statement.
Since we do a mapping between openmrs objects tp fhir resources, it would be best to have a dedicated wiki page for each resource containing the mapping details and the supported APIs. I think it’s more clean way. But agreed that it need to be maintained properly and that overhead is associated with that. When we track issues with JIRA we definitely need to look at whether particular ticket lead to have a impact on documentation change. It will solve some overhead in managing APIs in wikis. But if we API can self documented then it would definitely less overhead to maintain.
