Document API with OpenAPI 3

[rolandgeider]

The general API documentation won't win any prices, we should improve (so it becomes usable) with something like drf-spectacular

[Onesco]

I would love to work on this @rolandgeider if the task is till open.

[rolandgeider]

Hi @Onesco ! Sure, the issue is yours

(also note that drf-spectacular is just a suggestion, something else might be better)

[devilkiller-ag]

Hi @rolandgeider, I also want to work on this issue if you allow.

[rolandgeider]

Hi @devilkiller-ag ! @Onesco is already working on this, but you might be able to help each other?

[Onesco]

alright, @devilkiller-ag just push your changes more frequently so that we will not have a lot of conflicts to fix. Thanks!

[Leptopoda]

Any news on this issue?

Is there at least a valid spec that could be published?
I'm interested in writing my own client while using the spec to generate the client side lib. This would be independent of the server side code generation so if there already is a spec I'd love to hear.

[rolandgeider]

Hi! Sadly not. At the moment your best shot is to take a look at the browsable api, most of the entries are should be self explanatory. What exactly did you want to interact with? (exercises, workouts, etc.)

[Leptopoda]

I wanted to rewrite the flutter client.

I and a friend of mine want to redo a lot of things (offline first, ios, new design, as much code generation and static analysis as possible ...)
No offense but we don't think the current code is in a state where it makes sense to reuse it, thus we wanted to rewrite it from scratch. Obviously it'll be open source so when this becomes a thing we can give the code back to this org if desired.

Having a spec would let us generate the code so we'd basically only need to write UI code and some glue code.

[rolandgeider]

that's a huge undertaking! 😅

In any case I still have two weeks of vacation that I need to take in march, so I'll have some time to take drf-spectacular for a spin, we might be lucky and it'll work for most things out of the box.

[Leptopoda]

that's a huge undertaking! sweat_smile

Yes it is 🙃
Nevertheless working a lot with code generation lately I don't think this is impossible.

Thanks for having a look into it.

[rolandgeider]

so it seems that while we obviously need to fine tune a lot of things, we can get pretty far by just installing drf spectacular

[Leptopoda]

That's awesome to hear!

keep me updated once something usable emerges

[rolandgeider]

I have installed the current version on the preview server. There's still some warnings and other fine tuning to do, but I think this can be already tested:

Schema file
Swagger UI
Redoc

[Leptopoda]

Thanks a lot.

I'm currently occupied in some other work but it's definitely something I'll be experimenting with.