Page Comparison

...

1. Model getGETModel(Representation)                                                                                                                                                                                                                                                                                                A resource that supports GET operations such as 'getAll', 'getByUniqueId', and 'search'' should override this method.                                                    ', and 'search'' should override this method.                                                                                 
2. Model getCREATEModel(Representation)                                                                                                                                                                                                                                                                                        A resource that supports CREATE operations should override this method.
3. Model getUPDATEModel(Representation)                                                                                                                                                                                                                                                                                        A resource that supports UPDATE operations should override this method.

You do not need to override these methods. However, if not, then their proper definitions won't appear in OpenMRS Swagger specification. Thus the resource won't show up in the live documentation here either.  (while the live demo swagger documentation can be found inside the advanced system adminstration section of the reference application on the demo server) either.

So it's recommended that you override these.

How to find which properties to be documented?

 getGETModelgetGETModel(Representation), getCREATEModel(Representation), and getUPDATEModel(Representation) methods correspond to getGetRepresentation(), getCreatableProperties(), and getUpdatableProperties() methods respectively. So they can be used as reference when documenting resources.

One can also look into corresponding test classes and its supportedClass

Example 

When documenting OrderSetResource1_12 one can use OrderSet.class, OrderSetResource1_12Test, and OrderSetController1_12Test as reference.

Documenting GET representation of a resource

Model getGETModel(Representation)

This method should return a Swagger Model object representing the GET representation schema for that resource. Returned Model may change depending on the representation type (DEFAULT, FULL, REF) being passed to that method.

If you don't understand the difference between DEFAULT, FULL, and REF representations, please refer to: 

REST Web Services API For Clients - Representations

Let's begin by documenting OrderSetResource1_12 

Its DEFAULT representation returns a JSON object with the following properties:

{ uuid, display, name, description, retired, operator, orderSetMembers }

• 'uuid', 'display', 'name', 'description' are just strings. 
• 'retired' can be either true or false.
• 'operator' can take the values ALL, ONE, or ANY
• 'orderSetMembers' is an array containing REF representations of OrderSetMember resources.

Based on the type of its properties, we can document the getGETModel for OrderSet resource as follows:

...

@SubResource(parent = ConceptResource1_8.class, path = "name", ..)
 public class ConceptNameResource1_8

As shown in the example, the definition name of ConceptResource1_8 is Concept (identified by the name property its @Resource annotation). So the definition name of ConceptNameResource1_8 sub-resource should be ConceptName. As you see, the definition name of a sub-resource is retrieved by appending the value of the path property of its @SubResource annotation to its parent's name.

RefProperty Type 

When one resource includes another resource as its property (e.g., conceptDatatype property on Concept object), the FULL representation of that property object is never included in the parent.

Eg :- DEFAULT representation of Concept resource includes the following reference properties:

name, datatype, conceptClass

name is a ConceptNameResource, datatype is a ConceptDatatypeResource, conceptClass is a ConceptClassResource.

In DEFAULT representation of a Concept resource

• DEFAULT representation of name is included
• REF representation of datatype is included
• REF representation conceptClass is included

So the code would be like:

model
  .property("name", new RefProperty("#/definitions/ConceptNameGet"))
  .property("datatype", new RefProperty("#/definitions/ConceptdatatypeGetRef"))
  .property("conceptClass", new RefProperty("#/definitions/ConceptclassGetRef"));

...