RESTWS-562 Improve Resource Definition Documentation (#288)

* RESTWS-562 Improve Resource Definition Documentation - adds swagger-core library * uses its Java API and model classes to construct and generate the swagger json. - introudce new methods which model objects used in constructing the definitions section: * getGETModel(Representation) : returns a object represting GET representation schema of resource * getCREATEModel(Representation) : returns a object representing CREATE representation shema of a resource * getUPDATEModel(Representation) : returns a object representing POST Update representation schema of a resource ex: PersonGet, PersonCreate, PersonUpdate - adds new test cases to: SwaggerSpecificationCreatorTest.java - adds support for multiple representation types GET schemas have support for representations: DEFAULT, REF, and FULL CREATE schemas have support for representations: DEFAULT, and FULL POST_UPDATE schemas have support for representations: DEFAULT * uses default schema for the shema of responses and parameters * Fixup, document undocumented methods
openmrs · Aug 25, 2017 · 639ad02 · 639ad02
1 parent e12f8c7
commit 639ad02
Show file tree

Hide file tree

Showing 103 changed files with 3,810 additions and 708 deletions.
diff --git a/OpenMRSFormatter.xml b/OpenMRSFormatter.xml
@@ -263,5 +263,6 @@
 <setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_angle_bracket_in_type_arguments" value="do not insert"/>
 <setting id="org.eclipse.jdt.core.formatter.never_indent_block_comments_on_first_column" value="false"/>
 <setting id="org.eclipse.jdt.core.formatter.keep_then_statement_on_same_line" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.join_wrapped_lines" value="false"/>
 </profile>
 </profiles>
diff --git a/...penmrs/module/webservices/rest/web/v1_0/resource/openmrs1_10/CareSettingResource1_10.java b/...penmrs/module/webservices/rest/web/v1_0/resource/openmrs1_10/CareSettingResource1_10.java
@@ -13,8 +13,11 @@
 import java.util.List;
 import java.util.regex.Pattern;
 
+import io.swagger.models.Model;
+import io.swagger.models.ModelImpl;
 import org.openmrs.CareSetting;
 import org.openmrs.api.context.Context;
+import org.openmrs.module.webservices.docs.swagger.core.property.EnumProperty;
 import org.openmrs.module.webservices.rest.web.RequestContext;
 import org.openmrs.module.webservices.rest.web.RestConstants;
 import org.openmrs.module.webservices.rest.web.annotation.Resource;
@@ -67,6 +70,16 @@ public DelegatingResourceDescription getCreatableProperties() {
 		throw new ResourceDoesNotSupportOperationException();
 	}
 
+	@Override
+	public Model getGETModel(Representation rep) {
+		ModelImpl model = (ModelImpl) super.getGETModel(rep);
+		if (rep instanceof DefaultRepresentation || rep instanceof FullRepresentation) {
+			model
+			        .property("careSettingType", new EnumProperty(CareSetting.CareSettingType.class));
+		}
+		return model;
+	}
+
 	/**
 	 * @see org.openmrs.module.webservices.rest.web.resource.impl.DelegatingCrudResource#newDelegate()
 	 */

diff --git a/.../org/openmrs/module/webservices/rest/web/v1_0/resource/openmrs1_10/OrderResource1_10.java b/.../org/openmrs/module/webservices/rest/web/v1_0/resource/openmrs1_10/OrderResource1_10.java
@@ -12,11 +12,17 @@
 import java.util.Date;
 import java.util.List;
 
+import io.swagger.models.Model;
+import io.swagger.models.ModelImpl;
+import io.swagger.models.properties.DateProperty;
+import io.swagger.models.properties.RefProperty;
+import io.swagger.models.properties.StringProperty;
 import org.apache.commons.lang.StringUtils;
 import org.openmrs.CareSetting;
 import org.openmrs.Order;
 import org.openmrs.Patient;
 import org.openmrs.api.context.Context;
+import org.openmrs.module.webservices.docs.swagger.SwaggerSpecificationCreator;
 import org.openmrs.module.webservices.rest.web.ConversionUtil;
 import org.openmrs.module.webservices.rest.web.RequestContext;
 import org.openmrs.module.webservices.rest.web.RestConstants;
@@ -102,6 +108,43 @@ public DelegatingResourceDescription getRepresentationDescription(Representation
 		}
 	}
 
+	@Override
+	public Model getCREATEModel(Representation rep) {
+		ModelImpl model = new ModelImpl()
+		        .property("encounter", new StringProperty().example("uuid"))
+		        .property("action", new StringProperty()
+		                ._enum(SwaggerSpecificationCreator.getEnumsAsList(Order.Action.class)))
+		        .property("accessionNumber", new StringProperty())
+		        .property("dateActivated", new DateProperty())
+		        .property("scheduledDate", new DateProperty())
+		        .property("patient", new StringProperty().example("uuid"))
+		        .property("concept", new StringProperty().example("uuid"))
+		        .property("careSetting", new StringProperty().example("uuid"))
+		        .property("dateStopped", new DateProperty())
+		        .property("autoExpireDate", new DateProperty())
+		        .property("orderer", new StringProperty().example("uuid"))
+		        .property("previousOrder", new StringProperty().example("uuid"))
+		        .property("urgency", new StringProperty()
+		                ._enum(SwaggerSpecificationCreator.getEnumsAsList(Order.Urgency.class)))
+		        .property("orderReason", new StringProperty().example("uuid"))
+		        .property("orderReasonNonCoded", new StringProperty())
+		        .property("instructions", new StringProperty())
+		        .property("commentToFulfiller", new StringProperty())
+
+		        .required("orderType").required("patient").required("concept");
+		if (rep instanceof FullRepresentation) {
+			model
+			        .property("encounter", new RefProperty("#/definitions/EncounterCreate"))
+			        .property("patient", new RefProperty("#/definitions/PatientCreate"))
+			        .property("concept", new RefProperty("#/definitions/ConceptCreate"))
+			        .property("orderer", new RefProperty("#/definitions/UserCreate"))
+			        .property("previousOrder", new RefProperty("#/definitions/OrderCreate"))
+			        .property("orderReason", new RefProperty("#/definitions/ConceptCreate"));
+		}
+		//FIXME missing prop: type
+		return model;
+	}
+
 	/**
 	 * @see org.openmrs.module.webservices.rest.web.resource.impl.BaseDelegatingResource#getCreatableProperties()
 	 */

diff --git a/.../openmrs/module/webservices/rest/web/v1_0/resource/openmrs1_10/OrderTypeResource1_10.java b/.../openmrs/module/webservices/rest/web/v1_0/resource/openmrs1_10/OrderTypeResource1_10.java
@@ -13,6 +13,11 @@
 import java.util.List;
 import java.util.regex.Pattern;
 
+import io.swagger.models.Model;
+import io.swagger.models.ModelImpl;
+import io.swagger.models.properties.ArrayProperty;
+import io.swagger.models.properties.RefProperty;
+import io.swagger.models.properties.StringProperty;
 import org.openmrs.OrderType;
 import org.openmrs.api.context.Context;
 import org.openmrs.module.webservices.rest.web.RequestContext;
@@ -146,4 +151,33 @@ public DelegatingResourceDescription getCreatableProperties() {
 		d.addProperty("conceptClasses");
 		return d;
 	}
+
+	@Override
+	public Model getGETModel(Representation rep) {
+		ModelImpl model = (ModelImpl) super.getGETModel(rep);
+		if (rep instanceof DefaultRepresentation || rep instanceof FullRepresentation) {
+			model
+			        .property("javaClassName", new StringProperty());
+		}
+		if (rep instanceof DefaultRepresentation) {
+			model
+			        .property("conceptClasses", new ArrayProperty(new RefProperty("#/definitions/ConceptclassGetRef")))
+			        .property("parent", new RefProperty("#/definitions/OrdertypeGetRef"));
+		} else if (rep instanceof FullRepresentation) {
+			model
+			        .property("conceptClasses", new ArrayProperty(new RefProperty("#/definitions/ConceptclassGet")))
+			        .property("parent", new RefProperty("#/definitions/OrdertypeGet"));
+		}
+		return model;
+	}
+
+	@Override
+	public Model getCREATEModel(Representation rep) {
+		return ((ModelImpl) super.getCREATEModel(rep))
+		        .property("javaClassName", new StringProperty())
+		        .property("parent", new StringProperty().example("uuid")) //FIXME type
+		        .property("conceptClasses", new ArrayProperty(new StringProperty().example("uuid")))
+
+		        .required("javaClassName");
+	}
 }
diff --git a/.../openmrs/module/webservices/rest/web/v1_0/resource/openmrs1_10/OrderableResource1_10.java b/.../openmrs/module/webservices/rest/web/v1_0/resource/openmrs1_10/OrderableResource1_10.java
@@ -13,6 +13,8 @@
 import java.util.Collection;
 import java.util.List;
 import java.util.Locale;
+
+import io.swagger.models.Model;
 import org.openmrs.ConceptClass;
 import org.openmrs.ConceptName;
 import org.openmrs.ConceptSearchResult;
@@ -184,6 +186,11 @@ public DelegatingResourceDescription getRepresentationDescription(Representation
 		return description;
 	}
 
+	@Override
+	public Model getCREATEModel(Representation rep) {
+		return null;
+	}
+
 	@PropertyGetter("display")
 	public String getDisplayString(ConceptSearchResult csr) {
 		ConceptName cn = csr.getConcept().getName();

diff --git a/.../module/webservices/rest/web/v1_0/resource/openmrs1_10/ProgramEnrollmentResource1_10.java b/.../module/webservices/rest/web/v1_0/resource/openmrs1_10/ProgramEnrollmentResource1_10.java
@@ -9,6 +9,12 @@
  */
 package org.openmrs.module.webservices.rest.web.v1_0.resource.openmrs1_10;
 
+import io.swagger.models.Model;
+import io.swagger.models.ModelImpl;
+import io.swagger.models.properties.ArrayProperty;
+import io.swagger.models.properties.BooleanProperty;
+import io.swagger.models.properties.DateProperty;
+import io.swagger.models.properties.RefProperty;
 import org.openmrs.PatientProgram;
 import org.openmrs.PatientState;
 import org.openmrs.api.context.Context;
@@ -93,6 +99,32 @@ public DelegatingResourceDescription getCreatableProperties() {
 		return d;
 	}
 
+	@Override
+	public Model getGETModel(Representation rep) {
+		return super.getGETModel(rep);
+	}
+
+	@Override
+	public Model getCREATEModel(Representation rep) {
+		return ((ModelImpl) super.getCREATEModel(rep))
+		        .property("states", new ArrayProperty(new RefProperty("#/definitions/ProgramenrollmentStateCreate")))
+		        .property("outcome", new RefProperty("#/definitions/ConceptCreate"));
+	}
+
+	@Override
+	public Model getUPDATEModel(Representation rep) {
+		return new ModelImpl() //FIXME use super.
+		        .property("dateEnrolled", new DateProperty())
+		        .property("states", new ArrayProperty(new RefProperty("#/definitions/ProgramenrollmentStateCreate")))
+		        .property("outcome", new RefProperty("#/definitions/ConceptCreate"))
+		        .property("location", new RefProperty("#/definitions/LocationCreate"))
+		        .property("voided", new BooleanProperty())
+		        .property("dateCompleted", new DateProperty())
+
+		        .required("dateEnrolled");
+
+	}
+
 	@Override
 	public DelegatingResourceDescription getUpdatableProperties() {
 		DelegatingResourceDescription d = new DelegatingResourceDescription();

diff --git a/...rg/openmrs/module/webservices/rest/web/v1_0/resource/openmrs1_10/ProgramResource1_10.java b/...rg/openmrs/module/webservices/rest/web/v1_0/resource/openmrs1_10/ProgramResource1_10.java
@@ -9,6 +9,10 @@
  */
 package org.openmrs.module.webservices.rest.web.v1_0.resource.openmrs1_10;
 
+import io.swagger.models.Model;
+import io.swagger.models.ModelImpl;
+import io.swagger.models.properties.RefProperty;
+import io.swagger.models.properties.StringProperty;
 import org.openmrs.Program;
 import org.openmrs.module.webservices.rest.web.RestConstants;
 import org.openmrs.module.webservices.rest.web.annotation.Resource;
@@ -60,6 +64,17 @@ public DelegatingResourceDescription getRepresentationDescription(Representation
 		return null;
 	}
 
+	@Override
+	public Model getCREATEModel(Representation rep) {
+		ModelImpl model = ((ModelImpl) super.getCREATEModel(rep))
+		        .property("outcomesConcept", new StringProperty().example("uuid"));
+		if (rep instanceof FullRepresentation) {
+			model
+			        .property("outcomesConcept", new RefProperty("#/definitions/ConceptCreate"));
+		}
+		return model;
+	}
+
 	@Override
 	public DelegatingResourceDescription getCreatableProperties() {
 		DelegatingResourceDescription description = new DelegatingResourceDescription();

diff --git a/...s/module/webservices/rest/web/v1_0/resource/openmrs1_10/TestOrderSubclassHandler1_10.java b/...s/module/webservices/rest/web/v1_0/resource/openmrs1_10/TestOrderSubclassHandler1_10.java
@@ -11,6 +11,11 @@
 
 import java.util.List;
 
+import io.swagger.models.Model;
+import io.swagger.models.ModelImpl;
+import io.swagger.models.properties.IntegerProperty;
+import io.swagger.models.properties.RefProperty;
+import io.swagger.models.properties.StringProperty;
 import org.apache.commons.lang.StringUtils;
 import org.openmrs.CareSetting;
 import org.openmrs.Order;
@@ -19,6 +24,7 @@
 import org.openmrs.TestOrder;
 import org.openmrs.api.OrderService;
 import org.openmrs.api.context.Context;
+import org.openmrs.module.webservices.docs.swagger.core.property.EnumProperty;
 import org.openmrs.module.webservices.rest.web.ConversionUtil;
 import org.openmrs.module.webservices.rest.web.RequestContext;
 import org.openmrs.module.webservices.rest.web.annotation.PropertyGetter;
@@ -123,6 +129,47 @@ public DelegatingResourceDescription getUpdatableProperties() throws ResourceDoe
 		return orderResource.getUpdatableProperties();
 	}
 
+	@Override
+	public Model getGETModel(Representation rep) {
+		OrderResource1_10 orderResource = (OrderResource1_10) Context.getService(RestService.class).getResourceBySupportedClass(Order.class);
+		ModelImpl orderModel = (ModelImpl) orderResource.getGETModel(rep);
+		orderModel
+				.property("laterality", new EnumProperty(TestOrder.Laterality.class))
+				.property("clinicalHistory", new StringProperty())
+				.property("numberOfRepeats", new IntegerProperty());
+
+		if (rep instanceof DefaultRepresentation) {
+			orderModel
+					.property("specimenSource", new RefProperty("#/definitions/ConceptGetRef"))
+					.property("frequency", new RefProperty("#/definitions/OrderfrequencyGetRef"));
+		} else if (rep instanceof FullRepresentation) {
+			orderModel
+					.property("specimenSource", new RefProperty("#/definitions/ConceptGet"))
+					.property("frequency", new RefProperty("#/definitions/OrderfrequencyGet"));
+		}
+		return orderModel;
+	}
+
+	@Override
+	public Model getCREATEModel(Representation rep) {
+		OrderResource1_10 orderResource = (OrderResource1_10) Context.getService(RestService.class)
+				.getResourceBySupportedClass(Order.class);
+		ModelImpl orderModel = (ModelImpl) orderResource.getCREATEModel(rep);
+		return orderModel
+				.property("specimenSource", new StringProperty().example("uuid"))
+				.property("laterality", new EnumProperty(TestOrder.Laterality.class))
+				.property("clinicalHistory", new StringProperty())
+				.property("frequency", new StringProperty().example("uuid"))
+				.property("numberOfRepeats", new IntegerProperty());
+	}
+
+	@Override
+	public Model getUPDATEModel(Representation rep) {
+		OrderResource1_10 orderResource = (OrderResource1_10) Context.getService(RestService.class)
+				.getResourceBySupportedClass(Order.class);
+		return orderResource.getUPDATEModel(rep);
+	}
+
 	public PageableResult getActiveOrders(Patient patient, RequestContext context) {
 		String careSettingUuid = context.getRequest().getParameter("careSetting");
 		String asOfDateString = context.getRequest().getParameter("asOfDate");

diff --git a/...mrs/module/webservices/rest/web/v1_0/resource/openmrs1_11/DrugIngredientResource1_11.java b/...mrs/module/webservices/rest/web/v1_0/resource/openmrs1_11/DrugIngredientResource1_11.java
@@ -12,6 +12,11 @@
 import java.util.ArrayList;
 import java.util.List;
 
+import io.swagger.models.Model;
+import io.swagger.models.ModelImpl;
+import io.swagger.models.properties.DoubleProperty;
+import io.swagger.models.properties.RefProperty;
+import io.swagger.models.properties.StringProperty;
 import org.openmrs.Drug;
 import org.openmrs.DrugIngredient;
 import org.openmrs.api.context.Context;
@@ -80,6 +85,42 @@ public DelegatingResourceDescription getUpdatableProperties() {
 		return getCreatableProperties();
 	}
 
+	@Override
+	public Model getGETModel(Representation rep) {
+		ModelImpl modelImpl = (ModelImpl) super.getGETModel(rep);
+		if (rep instanceof DefaultRepresentation || rep instanceof FullRepresentation) {
+			modelImpl
+					.property("uuid", new StringProperty())
+					.property("display", new StringProperty())
+					.property("strength", new DoubleProperty());
+		}
+		if (rep instanceof DefaultRepresentation) {
+			modelImpl
+					.property("ingredient", new RefProperty("#/definitions/ConceptGetRef"))
+					.property("units", new RefProperty("#/definitions/ConceptGetRef"));
+		} else if (rep instanceof FullRepresentation) {
+			modelImpl
+					.property("ingredient", new RefProperty("#/definitions/ConceptGet"))
+					.property("units", new RefProperty("#/definitions/ConceptGet"));
+		}
+		return modelImpl;
+	}
+
+	@Override
+	public Model getCREATEModel(Representation rep) {
+		return new ModelImpl()
+				.property("ingredient", new StringProperty().example("uuid"))
+				.property("strength", new DoubleProperty())
+				.property("units", new StringProperty().example("uuid"))
+
+				.required("ingredient");
+	}
+
+	@Override
+	public Model getUPDATEModel(Representation rep) {
+		return getCREATEModel(rep);
+	}
+
 	/**
 	 * @see org.openmrs.module.webservices.rest.web.resource.impl.DelegatingSubResource#getParent(java.lang.Object)
 	 */

diff --git a/...va/org/openmrs/module/webservices/rest/web/v1_0/resource/openmrs1_11/ObsResource1_11.java b/...va/org/openmrs/module/webservices/rest/web/v1_0/resource/openmrs1_11/ObsResource1_11.java
@@ -9,6 +9,9 @@
  */
 package org.openmrs.module.webservices.rest.web.v1_0.resource.openmrs1_11;
 
+import io.swagger.models.Model;
+import io.swagger.models.ModelImpl;
+import io.swagger.models.properties.StringProperty;
 import org.openmrs.Obs;
 import org.openmrs.module.webservices.rest.web.RestConstants;
 import org.openmrs.module.webservices.rest.web.annotation.Resource;
@@ -35,6 +38,20 @@ public DelegatingResourceDescription getRepresentationDescription(Representation
 		return description;
 	}
 
+	@Override
+	public Model getGETModel(Representation rep) {
+		return ((ModelImpl) super.getGETModel(rep))
+		        .property("formFieldPath", new StringProperty())
+		        .property("formFieldNamespace", new StringProperty());
+	}
+
+	@Override
+	public Model getCREATEModel(Representation rep) {
+		return ((ModelImpl) super.getCREATEModel(rep))
+		        .property("formFieldPath", new StringProperty())
+		        .property("formFieldNamespace", new StringProperty());
+	}
+
 	/**
 	 * @see org.openmrs.module.webservices.rest.web.resource.impl.BaseDelegatingResource#getCreatableProperties()
 	 */