Open fxjordan opened 2 years ago
In order to document API parameters properly, we should first migrate from the custom coded MultipartHelper
class to standard jax-rs annotation @FormParam
which should make the code much more readable (see https://mkyong.com/webservices/jax-rs/jax-rs-formparam-example/ for usage)
This way, we could remove all the duplicated classes mentioned in #17
Next problem for documentation: Unlike the other services, the quest and streak services use JSON for request data representation. However, again, the existing tools of JAX-RS / Jersey are not used, and the methods only take a raw array as input (byte[] content
) and parse it manually.
Example:
https://github.com/rwth-acis/Gamification-Framework/blob/631d06e29607d25ede08416d9b4bf8859ea182b5/GamificationQuestService/src/main/java/i5/las2peer/services/gamificationQuestService/GamificationQuestService.java#L263-L271
This does not allow for proper documentation of the different parameters. Therefore, we should refactor these methods to take an object of type, e.g., NewQuest
, which declares all the parameters as fields. On these fields, we can add validation and Swagger documentation annotations.
Currently, a lot of knowledge was only communicated verbally about how to get started with the Gamification Framework. Also, developers need to look into the different java
GamificationXYZService
classes in order to find endpoint URLs and argument names.We should at least provide a short introduction on how to build requests (authentication, request content type). Additionally, it would be nice to have a generated
swagger.json
from the existing Swagger annotations. This file can either be read by developers directly, or it can be transformed to a markdown / HTML documentation of the API.