GSoD 2019: Improved REST API Documentation

@dkayiwa, can I get an example of a GET request for the patientIdentifier type? also I am able to find the documentation about the person attributes, but not the person resource in general

https://qa-refapp.openmrs.org/openmrs/ws/rest/v1/patientidentifiertype

Is this of help? https://github.com/openmrs/openmrs-module-webservices.rest/blob/master/omod-1.9/src/test/java/org/openmrs/module/webservices/rest/web/v1_0/controller/openmrs1_9/PersonController1_9Test.java

Thanks @dkayiwa, appreciate it

I also need a POST response example for patientIdentifierType, also could you tell me how I can generate this response by myself ?

Is this of help? https://github.com/openmrs/openmrs-module-webservices.rest/blob/master/omod-1.8/src/test/java/org/openmrs/module/webservices/rest/web/v1_0/controller/openmrs1_8/PatientIdentifierTypeController1_8Test.java

@dkayiwa I was actually looking for the real-world example values for this :

    "name": "string",
    "description": "string",
    "format": "string",
    "formatDescription": "string",
    "required": true,
    "checkDigit": true,
    "validator": "string",
    "locationBehavior": "REQUIRED",
    "uniquenessBehavior": "string"

I am unable to find the real-world example for this, this is a patientIdentifierType resource object which we need to send in the body

Did you get any errors while trying to make such a POST?

@dkayiwa I do not know what are the sample values of the keys?

@batbrain7, have you tried requesting patient identifier types from demo.openmrs.org?

@burke I do not know what are the sample values to put in the body of the post request,

@batbrain7 are you able to create a new patient identifier type from the user interface? https://wiki.openmrs.org/display/docs/Adding+A+New+Patient+Identifier+Type

Hi @burke

Can we merge this PR I pushed all fixes for all reviews

And this is new PR regarding encounter type

@ayesh, I’ve reviewed your PRs.

@batbrain7, I temporarily added a patient identifier type on demo and then fetched it using REST (I’ve removed extraneous properties for your example):

$ http -ba admin:Admin123 https://demo.openmrs.org/openmrs/ws/rest/v1/patientidentifiertype?v=full | jq ".results[1]"
{
  "display": "Amani Identifier",
  "name": "Amani Identifier",
  "description": "Medical record number for Amani Health System",
  "format": "\\d{1,10}-\\d",
  "formatDescription": "Up to ten digts followed by a hyphen and another digit",
  "required": false,
  "validator": "org.openmrs.patient.impl.LuhnIdentifierValidator",
  "locationBehavior": "NOT_USED",
  "uniquenessBehavior": "UNIQUE"
}

@ayesh & @batbrain7, we’re starting to accrue a decent set of resources. Let’s move all of the resource folders under a single /docs folder in the repo. The top level will contain README, LICENSE, CONTRIBUTING, and the code needed to build the documentation into a /dist folder (/dist should be added to our .git-ignore file if it’s not there). I’d like to start focusing on the front end documentation (overview, authentication, etc.) and begin presenting it with a tool like ReDoc so we can start getting feedback from the community.

1 Like

Hi @burke

Yes let’s start focusing on it :slightly_smiling_face:

But I think redoc has it’s own limitation according to the research I did it is depending on the provided swagger/openAPI spec documentation.(Basically not lot mark down files can be presented)

To overcome the above limitations slate was introduced

@burke

Something like this

https://akayeshmantha.github.io/OpenMRS-docs/#current-version

1 Like

Yes!!! Let’s get this running in our repo. I can point rest.openmrs.org to it.

If we can host this and make it easy for folks to see how to contribute to the documentation, that would be a great step forward.

@dkayiwa can you provide me with an example of the body for the POST to create a person. I am trying to create a person, but I get the error code 403 and forbidden. Here is the POST body that I need to populate :

    {
  "names": [
    {
      "givenName": "string",
      "middleName": "string",
      "familyName": "string",
      "familyName2": "string",
      "preferred": true,
      "prefix": "string",
      "familyNamePrefix": "string",
      "familyNameSuffix": "string",
      "degree": "string"
    }
  ],
  "gender": "M",
  "age": 0,
  "birthdate": "string",
  "birthdateEstimated": true,
  "dead": true,
  "deathDate": "string",
  "causeOfDeath": "string",
  "addresses": [
    {
      "preferred": true,
      "address1": "string",
      "address2": "string",
      "cityVillage": "string",
      "stateProvince": "string",
      "country": "string",
      "postalCode": "string",
      "countyDistrict": "string",
      "address3": "string",
      "address4": "string",
      "address5": "string",
      "address6": "string",
      "startDate": "string",
      "endDate": "string",
      "latitude": "string",
      "longitude": "string"
    }
  ],
  "attributes": [
    {
      "attributeType": "uuid",
      "value": "string",
      "hydratedObject": "uuid"
    }
  ],
  "deathdateEstimated": true,
  "birthtime": "2019-11-01T11:01:47.659Z"
}

@batbrain7, what have you tried? Did you try given name, family name, gender, birthdate (like “1970-12-01”), and a single address with address1, city, state, and postal code, and no person attributes?

@burke

Can we review this 2 PR’s

@burke

Can I have access to our google doc

https://docs.google.com/document/d/1IKzjfl07HVHubzsiy-8ZuYYJQQX9nIpMK-tLUczn3EY/edit

Hm seems like access revoked

thanks @burke that worked, I have also made a PR for the same