OpenMRS webservices.rest – Swagger Spec


This guide is for my own reference and for those who unfamilar with OpenMRS Swagger Spac and for he who is a starter yet willing to contribute to the spec. First to see the interactive api in action one could visit either one of the following urls

https://qa-refapp.openmrs.org/openmrs/module/webservices/rest/apiDocs.htm
https://demo.openmrs.org/openmrs/module/webservices/rest/apiDocs.htm

(or from any other OpenMRS reference application instances on the web in that matter)

If you’ve got a local server instance running, the url would be something like:
http://localhost:8080/openmrs/module/webservices/rest/apiDocs.htm

You might first need to login if you are to access the documentation page directly from its uri. Or you could navigate through the path Advanced Administration > REST Web Services > API Documentation once logged-in.

You should be able to make api calls directly from the Swagger ui. Let’s make a curl request instead:

curl -u admin:Admin123 https://demo.openmrs.org/openmrs-standalone/ws/rest/v1/session

The default username and password of the demo servers as of today is admin and Admin123.

For those who want to contribute to the module should first get a local copy of its source code:

git clone https://github.com/openmrs/openmrs-module-webservices.rest
cd openmrs-module-webservices.rest && mvn clean install

Generation of the Swagger Spec is mainly handled by the class: SwaggerSpecificationCreator.java
What it does, basically is to return a json string which includes api resources and their operations in a format that complies with The OpenAPI Specification.

The generated raw swagger json will be in the path:
https://<qa-refapp.openmrs.org>/openmrs/module/webservices/rest/swagger.json

The requests to the above uri is handled by the controller SwaggerSpecificationController.java

To view swagger.json with syntax highlighting and in a collapsible tree structure, I’ve found few useful addons. One such is the JSON-DataView for Firefox.

While working on the issue RESTWS-562 – (an attempt to improve the existing Swagger spec), this site has been a great help: jsoneditoronline.org (which has an interactive ui for editing and formatting json data)

All bugs related to module can be found in here. The issues are labeled under RESTWS-..

Leave a comment

Your email address will not be published. Required fields are marked *