Decide on Automating API Docs - Githubissues

Monstarrrr / rebutify

Web platform where experts submit rebuttals to common arguments against social justice movements.

https://rebutify.org

5 stars 1 forks source link

Decide on Automating API Docs #210

Closed Monstarrrr closed 1 week ago

Monstarrrr commented 1 week ago

Technology for Automating API Docs

Impact: 🟡 Medium
Status: 🔒 Decided
Deciders & Confidence:
- @purple-void 3.5/5
- @seporterfield 5/5
- @Monstarrrr 5/5
- Technical Story: [related URLs] e.
- 44
- 73
- https://www.saaspegasus.com/guides/modern-javascript-for-django-developers/apis
- Last updated: [27-05-2024]

Context and Problem Statement

What technology will we use to generate and serve an OpenAPI spec?

Decision Drivers

ease of use for front-end dev
interoperability with tools relying on a standardized OpenAPI spec

Considered Options

drf-spectacular

This 2.2k star library is built to "extract as much schema information from DRF as possible".

Good, because it is fast easy to implement (PR already done)
Good, because it has strong community support
Good, because authentication routes also show up in the spec
Good, because it allows django to serve swagger ui which makes testing API routes simple
Good, because it allows customizing the autogenerated documentation

Vanilla implementation

Bad, because it would take very long

Decision Outcome

Chosen option: drf-spectacular Reason(s): only feasible option for our time

Positive Consequences

docs in both swagger and redoc UI formats
new tooling we introduce can consume the docs via the corresponding endpoint

Negative Consequences