-
Notifications
You must be signed in to change notification settings - Fork 523
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RESTWS-562 Improve Resource Definition Documentation #288
Conversation
@gayanW, thanks for your PR! By analyzing the history of the files in this pull request, we identified @teleivo, @tmarzeion and @psbrandt to be potential reviewers. |
@gayanW did you see the travis failure? |
@dkayiwa minor mistake : ) please check now |
@bholagabbar, are you reviewing this PR? For this to work, do developers have to implement the |
Unless introducing a new resource, it is not mandatory to implement those methods. However if not, their definitions won't appear in the swagger doc. But it will not affect the program in any other way. I've updated almost all the resources within the rest module. Methods such as getRepresentationDescription(..) is no longer being used to generate the documentation. However I did not remove any of these existing code in case they are being accessed by other modules. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Have reviewed a few files. Can't possibly go through them all at once. Will get back to it in a while. Do resolve/provide justifications for the ones I have marked meanwhile
boolean limit = false, startIndex = false; | ||
|
||
for (Parameter p : o.getParameters()) { | ||
for (io.swagger.models.parameters.Parameter p : o.getParameters()) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gayanW Not good coding practice IMO. import io.swagger.models.parameters.Parameter
and then use it. You've removed import org.openmrs.module.webservices.docs.swagger.Parameter
so it shouldn't cause a conflict right?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll replace all possible fully qualified class names.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done
@@ -9,6 +9,7 @@ | |||
*/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gayanW AnimalResource? Are you using tests for the stock swagger project? The animal store one? We need to have tests with patients and other proper openmrs classes
@@ -9,6 +9,7 @@ | |||
*/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gayanW It seems as though all the animal tests have just been stashed here. We can't have that. Can you justify your decision? It doesn't make sense to me
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
They have always been there. I only implemented the missing methods. It seems that they are only used by RestServiceImplTest
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dkayiwa What do you think? Should we have these tests? On the surface, AnimalClassResource
doesn't seem right inside an OpenMRS webservices module. Ideally we should be replacing these tests?
import java.util.Map.Entry; | ||
import java.util.Set; | ||
|
||
import io.swagger.models.*; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gayanW No wildcard imports. Period. Remove all of them and replace them with individual classes
omod-common/pom.xml
Outdated
<exclusions> | ||
<exclusion> | ||
<groupId>org.slf4j</groupId> | ||
<artifactId>slf4j-api</artifactId> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Error in XML formatting. Indentation is off
.property("endDate", new DateProperty()) | ||
.property("patientUuid", new StringProperty()); | ||
} | ||
//FIXME missing props |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gayanW did you see the above question mark?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dkayiwa IMO. lines marked FIXME that'll update the swagger properties will be better fix in a new separate issue.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will be fixed in: https://issues.openmrs.org/browse/RESTWS-676
@@ -9,12 +9,14 @@ | |||
*/ | |||
package org.openmrs.module.webservices.rest.web.v1_0.resource.openmrs1_9; | |||
|
|||
import io.swagger.models.Model; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this import being used here? Get rid of all unused imports in all the files if they exist
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done
FYI: IMO reviewing all resource classes is not going to be practical. It takes a lot of effort to find right attributes, and their respective types of a resource. I had to go through ones' parent classes, supportedClass, respective tests and so on. So I think It will suffice therefore to review SwaggerSpecificationCreator and the generated json spec. And may be just go through the resource classes. |
@gayanW did you see the merge conflicts on this? |
@dkayiwa The pr was gone stale. I just rebased it. |
@gayanW your pull request deals with a lot of things, formatting, imports, classname changes, etc. |
@bholagabbar @dkayiwa I squashed, and eliminated those formats/fix done on classes that are not directly relevant to our use case. So now we have only the changes made to the SwaggerSpecificationCreator and the resource classes. To my understanding, it's inevitable not to update all the resources, because then it would result in a partial swagger spec. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dkayiwa I have had a cursory glance at the changes. With most of these as swagger spec definitions, I believe merging the PR and further testing it on the QA instance would be the right way to go.
.property("previousOrder", new RefProperty("#/definitions/OrderCreate")) | ||
.property("orderReason", new RefProperty("#/definitions/ConceptCreate")); | ||
} | ||
//FIXME missing prop: type |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gayanW is this comment relevant?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In 1_8, orderType
is marked required. But in 1_10 it seems that this property is no longer required to place a new order. For those that I thought would need extra testing, and research, I put FIXME. May we fix these in a new PR?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mention this in the next issue you create where you will be fixing the changes you removed formatting, etc not directly relevant to this issue
@@ -102,6 +108,43 @@ public DelegatingResourceDescription getRepresentationDescription(Representation | |||
} | |||
} | |||
|
|||
@Override | |||
public Model getCREATEModel(Representation rep) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Did you intentionally name this as getCREATEModel instead of getCreateModel?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
May be I thought that it was more readable. Anyway I could change that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do your mentors prefer getCREATEModel to getCreateModel?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think they commented on this. If you prefer getCreateModel
over getCREATEModel
, I can refactor.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you ask them and tell me what they prefer?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since GET, CREATE and UPDATE are actions that are being documented, captial cases indicating the action makes sense. I understand the deviation from camelCase but this makes the code more readable. I am fine with this. @dkayiwa I leave the final decision upto you
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I just wanted to make sure that you are aware of this. 😊
|
||
@Override | ||
public Model getCREATEModel(Representation rep) { | ||
return super.getCREATEModel(rep); //FIXME missing props |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are the FIXME supposed to be addressed in another pull request?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes. As discussed with Shreyans they will be fixed in a separate issue. These will require minor to no change at all. But may need testing and discussion.
@@ -74,7 +79,7 @@ public DelegatingResourceDescription getRepresentationDescription(Representation | |||
description.addProperty("validator"); | |||
description.addProperty("locationBehavior"); | |||
description.addProperty("uniquenessBehavior"); | |||
description.addProperty("validator"); | |||
description.addProperty("validator"); //FIXME duplicate |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When you do plan to fix the above?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gayanW create an issue on JIRA and paste a link here for reference
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@bholagabbar should I create, before or after this is being merged?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
create it now and paste the link, is there an issue with this?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
public class SwaggerSpecificationCreatorTest extends BaseModuleWebContextSensitiveTest { | ||
|
||
@Test | ||
public void mainTest() { | ||
String baseUrl = "localhost:8080/openmrs/ws/rest"; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this work even when the 8080 port is used by some other process?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I just tested this with different listening and open ports. And it has no effect on where the API is exposed. It changes the baseUrl of the swagger json, and as this is a test it has no much significance.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In either case, hard coding a port number is not good practice. Make BaseUrl generic if it doesn't make a difference
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The port or the baseUrl being passed in here have no actual significance. As you could see with the old tests: https://github.com/gayanW/openmrs-module-webservices.rest/blob/281145120aee4664d048b0b1cb2f6264828d2035/omod/src/test/java/org/openmrs/module/webservices/rest/doc/SwaggerSpecificationCreatorTest.java#L142
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm alright. I'm convinced when you tell me that it has no significance/doesn't affect the code but having something like 'http:8080/localhost' is never good practice even if it's in tests. Just assign it as 'base_url/ws/rest` or something if it doesn't have any significance.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Changed to "host/openmrs/ws/rest"
FYI: https://swagger.io/docs/specification/2-0/api-host-and-base-path/
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ok this looks good
public Model getGETModel(Representation representation) { | ||
return null; | ||
} | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see a number of these methods simply return null. Shouldn't it be enough not to have them and assume that whichever class does not have them, null it is? Am looking at reducing the amount of code that we have to maintain.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dkayiwa
Yeah I see. But isn't that good that we enforce them? So when creating a resource class one knows that he should document them? BTW I'm following a similar approach as it's done in old getRepresentationDescription
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dkayiwa It's your call :) ideally only a test resource should return null values. Other resources will either implement or could just inherit from its parent
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In which class or interface are these methods declared?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Almost all resources inherit: https://github.com/gayanW/openmrs-module-webservices.rest/blob/270edab5222fdfd7b8a77adf209e6d280c1688af/omod-common/src/main/java/org/openmrs/module/webservices/rest/web/resource/impl/BaseDelegatingResource.java#L76-L101
Yeah I just saw a minor improvement that could be done. I'll push it with the added doc.
I documented the methods. see: https://github.com/gayanW/openmrs-module-webservices.rest/blob/b9a970ed4ec1c1696410e24489c3445181a7aca1/omod-common/src/main/java/org/openmrs/module/webservices/rest/web/resource/impl/DelegatingResourceHandler.java#L93-L126 And updated the issue description as well. |
@gayanW i have tried running these changes locally and saw a few more resources show up like "address", "allergy", "answer". Was this an intentional side effect of this pull request? Or is it something else? |
@dkayiwa Swagger UI separates path operations by their tags. With the changes, subresources were tagged by their resource name instead of their parent name.
So in the older spec tag is set to patient, but here it's allergy. I didn't give enough thought in to this. May be its better that we use the parent tag..? Let me know. I'll keep changes ready. |
@gayanW can you engage the community to see what others say? |
I changed it to the old way. (FYI: only these 2 lines were changed - SwaggerSpecificationCreator.java#L602 SwaggerSpecificationCreator.java#L1001) |
Ok let me compile and test it out again. |
@dkayiwa The changes will be visible once we upgrade the ui: RESTWS-560 |
So how will i see the changes before RESTWS-560 is done? |
@dkayiwa Some changes are still visible with the old ui. But if you want to see all the changes, you may try this out: http://editor.swagger.io/ And paste the content of the swagger.json there. |
How long would it take to finish the other ticket? |
@dkayiwa It is better to work on it once this is finished. |
@gayanW i have just tested again and noticed that the q parameter is not highlighted as required, with your changes. Was that intentional? https://qa-refapp.openmrs.org/openmrs/module/webservices/rest/apiDocs.htm#!/order/getAllOrders |
@dkayiwa q param is not marked required for resources that supports fetchAll. If there's more than one query param, then it is not marked required either. |
- 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
@bholagabbar what behavior do you get in regards to the above? |
.property("accessionNumber", new StringProperty()) | ||
.property("dateActivated", new DateProperty()) | ||
.property("scheduledDate", new DateProperty()) | ||
.property("patient", new StringProperty().example("uuid")) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Where are these examples displayed?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
http://localhost:8080/openmrs/module/webservices/rest/apiDocs.htm#!/order/createOrder
See in the 'Example Value' section.
{
"encounter": "uuid",
"action": "NEW",
"accessionNumber": "string",
"dateActivated": "2017-08-24",
"patient": "uuid",
"concept": "uuid",
...
}
public Model getGETModel(Representation representation) { | ||
return null; | ||
} | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is the difference between a resource like this which returns all nulls and those that do not? Or was it simply a lack of time to implement?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No it's not due to lack of time. I had enough time :) I've been tracking undocumented resources by validating the swagger. Some how they were missed. I'll check and fix those.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And i found a good number of them.
return null; | ||
} | ||
|
||
@Override |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Were these intentionally left null?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we need to document handlers? I don't think they appear either as a resource or a property. If needed let me know.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Then in that case we should not have these methods in them.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
However they implements getRepresentationDescription, getCreatableProperties, and getUpdatableProperties. Is handler considered a resource or can they be a property of some other resource?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would not consider it as a resource. But putting this aside, can you ensure that all other non search handlers that should not just return null, are doing what they should?
@@ -99,6 +100,16 @@ public DelegatingResourceDescription getUpdatableProperties() { | |||
} | |||
|
|||
@Override | |||
public Model getGETModel(Representation representation) { | |||
return null; | |||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Were these intentionally left null? And many more others.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
SwaggerSpecificationCreator#mainTest() does not detect resources from all versions. This is not really an issue. But it will be useful, if it could detect all, so one can generate the spec just from running this test, instead of having to restart the server.
Can it be done?
@dkayiwa Test resource classes also returns null, as they are not needed. Except these, all other classes are documented. |
Ok cool. |
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
Swagger before: http://www.jsoneditoronline.org/?id=6ac2d0c797f5e8e4060d09b62b300b04
Swagger after: http://jsoneditoronline.org/?id=d692754b9b4543f7388572317dc10400