search

OpenTechSchool-Leipzig / heimspiel-backend

Heimspiel (Backend)
https://heimspiel.herokuapp.com/
GNU Affero General Public License v3.0
0 stars 0 forks source link

Document API using Swagger / OpenAPI #7

Open dkellner opened 4 years ago

dkellner commented 4 years ago

Use something like https://github.com/axnsan12/drf-yasg and make sure the output is documented well enough. We'll probably need to add some docstrings here and there.

normade commented 4 years ago

Started this issue (branch) and needed to add custom serializers to only display the score_reports response in the docs which seems kind of overengineered? Also I am not so satifsfied having all those serializers of that single view in a separate file and having a serializers.py additonally whicht might be confusing? Any thoughts here, @dkellner?

Due to black formatting the branch is unfortunately messed up. Main changes in: src/heimspiel_core/views.py and src/heimspiel_core/score.py.

dkellner commented 4 years ago

I actually like the serializers - but we should use them for serializing our response, too. That way nobody can accidentally add fields to the response and forget about documenting them.

The file structure is confusing, indeed. That's a leftover of the Hackathon we should clean up. How about moving score_reports and the scoring-related serializers to a new scoring-module?

normade commented 4 years ago

Yes, thought also like that, to use it for the response too, but there are some issues with the tests then that need to be fixed (the URL check is not valid) and I was lazy 😅 and so I decided first to discuss it in general. But I agree to use Serializers, it is helpful and keeps the stuff clean.

👍 for new scoring module. Personally I would prefer that over having everything in the core serializers.py. Also scoring might be growing with time, so it has already its own place. How about the badge? Should a badge also considered a kind of scoring? Somehow it belongs there but it is more a result of a score? Or can you receive a badge just for - let's say - downloading PDF quests? Or setting up a team or so? In that case we could think about having a reward module or so?

dkellner commented 4 years ago

So far we didn't discuss this and it never occured to me - but making rewards/badges independent of scoring is a great idea! It's much more flexible this way and we could even create badges for sharing your "world" with other players, depending of how many "visitors" you got (e.g. after 100 visitors you are rewarded a special badge you cannot earn otherwise).