search

rwth-acis / Gamification-Framework

Gamification of Community Information Systems
6 stars 2 forks source link

Provide more documentation about API and authentication #32

Open fxjordan opened 2 years ago

fxjordan commented 2 years ago

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.

fxjordan commented 2 years ago

In order to document API parameters properly, we should first migrate from the custom coded MultipartHelperclass 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

fxjordan commented 2 years ago

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.