This page contains the details of a technical writing project accepted for Season of Docs.
- Open source organization:
- Technical writer:
- Project name:
- Extending User Friendly GitHub Documentation for REST API
- Project length:
- Standard length (3 months)
Enhance the OpenMRS Swagger-based REST API documentation to add guidance on the use of the API.
The OpenMRS REST API is one of the key mechanisms for developers to access data from OpenMRS. There is already a Swagger based auto-generated documentation of the OpenMRS Webservices API and a static GitHub based documentation as well, we are supposed to extend that GitHub based documentation in this Season of Docs.
After a bit of research on OpenMRS Talk as Burke suggested, I got to know that this project started back in 2017 as a GSOC project. With Gayan Weerakutti where the main objective was to improve the existing documentation of the OpenMRS REST API, by improving its Swagger Specification and through improvements to the way its Swagger Specification is being generated so that a better version of the swagger documentation itself is generated. All the relevant details accomplished in the project were summarised here in this OpenMRS talk post and were quite useful.
Then, in 2019, this project was revamped, and we moved on from Swagger documentation tweaks producing variations on this. Instead, we developed a static GitHub friendly documentation that we are going to extend in this season of Docs.
So a brief of the current project proposal that I intend to describe is :
- Adding playground support for the slate documentation just like the Swagger ""try-out"" feature.
- Refactoring and improving the work done up till now.
- Finding and adding the missing resources.
- Adding a bit more description to the console section of the docs
- Come up with examples in different languages.
- Adding Playground support for testing APIs examples
I have used this feature in the swagger documentation of the OpenMRS hosted at the demo server, and it's a really convenient tool to have in any API documentation. I researched a bit here, and it's not that difficult to embed Swagger-UI spec into the current static documentation. Using show hide toggles and using the current swagger documentation code we have. This way we can even ensure that the try-out feature remains live with the current API specifications, this is one way I believe we could integrate playground features into our current static documentation.
- Refactoring and improving the work done up till now
Checking the current curl examples
This section is one of the main emphasis of this project this year, At present, only curl examples are there on the GitHub API docs some of which can't be directly run on the demo server to check directly from the browser. I will test all the current endpoints and maintain a simple document with various curl examples' responses we get on running those curl requests. I will use Postman in addition to the inbuilt try-out feature in the swagger documentation to accomplish this task if required.
Missing API responses on some of the examples
Some responses have been added for the present curl examples, but some of the curl examples do not have responses. I think even if the responses aren't verbose which is usually the case with operations like purging the resource, we should have an example JSON API Response though we have documented all possible response codes and the reason to get them I think this would make the examples across the API documentation more uniform !!
Missing working examples on various operations
I think this will be the most important part of refactoring the previously accomplished work in the API documentation, there are concrete examples in the documentation which can be directly executed with cURL, but some of them are a bit abstract which gives a good reference to experienced devs but leaves the newcomers in a state of bother. As I could gather from this post in OpenMRS talk that good examples are priceless, so apart from adding examples of work we could support syntax highlighting which is indeed not much work it pretty much comes bundled with slate which makes this quite easy to do as I found out here,
As burke has emphasized many times in his post preferring simplicity and descriptiveness in docs in place of good UI and shiny interface I would adhere to these principles and try and make the previously documented endpoints as descriptive as possible by talking to developers who are currently working on OpenMRS Webservices API and engaging the community, just like I did in the talk post for gathering descriptions for the attribute types for the forms resources which were not clear to me in my PR here. I would really work on things priority wise, talking to my mentors, and deciding which are the things that really add value to the docs and need to be accomplished first.
Adding Use cases as an explicit headline
I have seen many API documentation just to get the hang of them and saw that all of them had use cases as an explicit headline, though we do have use cases they aren't explicitly visible they are somewhat fused inside the definitions and examples that follow after the definitions of the resources and subresources, I think we should make the effort of separating Use-Cases as a separate entity in the documentation so that developers don't really have to search through the definitions inferring the use cases rather, they can just look them up.
Finding and documenting the missing resources
The current project state has resources listed here, but on seeing the latest version of the swagger documentation here, I could figure out many resources which could be added to the current suite of resources in the GitHub friendly API docs with the description as accomplished with other resources during the Season of Docs 2019. I will discuss the topics which need to be added to the docs and add them suitably.
I have been a part of OpenMRS community for a while now. I am an active contributor to the Android Client project where I interact with the APIs often to interact with the servers. Hence, I feel I can work on this project of extending the API docs pretty well since I can view my work as a developer myself and evaluate if it really eases the work of other developers or not,I have become familiar with the tools used for the user-friendly documentation repository hosted here, I have made several contributions to this repo as well in order to get familiar with the repository and tools i.e. slateUI , Since an API is thought to be as good as its documentation so I would love to make the OpenMRS Rest APIs a bit better by improving its documentation.
I will make sure to communicate the progress weekly with a talk post which will help to get the feedback from the community and work in close correlation with my mentor and community to get the best out of this period of documentation.