Hi!
i guess the question isn’t strictly a Django question, but as I am using Django Rest Framework I thought I try my luck and learn how others approach the issue I am facing.
The DRF-docs for Documenting your API are mainly concerned with generating the docs based on existing code. And from what I see django-spectacular seems to be the most complete solution at the moment.
And though I see the value of generated docs based on actual code, I wonder if I am missing a piece of the puzzle: Assuming there is a backend team and a frontend team. Relying on generated docs in strict sense would mean that the backend team has to finish the work before the frontend team can start.
So I wonder how to combine the generated docs-approach with an approach, where you write the API specs first, so that backend and frontend can start in parallel and rely on shared idea/contract. In my ideal world the first step of a new feature development would be to open an Merge Request simply with the a draft of the docs for the new or changed API.
Is there a way to incorporate the manual API drafts into the doc generators that I a missing?
Or should I treat the draft/development of new or changed APIs as separate task with separate tooling?
It would be glad to learn how others deal with this?
Cheers,
Andreas