Backend API Documentation Guide

This page explains how our API documentation is generated, how to access it, and how to ensure your endpoints are correctly documented.

1. Overview

We use drf-spectacular to generate OpenAPI 3.0 compliant documentation. Unlike older tools, drf-spectacular is the modern standard for Django Rest Framework (DRF), offering better support for type hints and complex serializers.

2. How the Documentation is Generated

• Introspection: drf-spectacular inspects our serializers.py, models.py, and views.py.
• Schema Creation: It creates a YAML/JSON schema representing all routes, request bodies, and response types.
• UI Rendering: This schema is then rendered by Swagger UI or ReDoc for a human-readable interface.

3. Accessing the Documentation

Once the server is running locally, you can access the documentation at:

• Swagger UI (Interactive): http://localhost:8000/api/docs/
• SReDoc (Reading-focused): http://localhost:8000/api/schema/redoc/
• Raw Schema: http://localhost:8000/api/schema/

4. How to Document Your Endpoints

For most standard ModelViewSet or GenericAPIView setups, drf-spectacular will handle everything automatically. However, to keep the documentation high-quality, follow these rules:

• A. Use Serializers for Everything: Always define serializer_class in your views. The documentation uses these to define the "Data Models" you see at the bottom of the Swagger page.

• B. Use Docstrings: The first line of your ViewSet or method docstring will become the Summary, and the rest will become the Description in Swagger.

• C. Customizing with @extend_schema: If an endpoint has special parameters or multiple response types, use the decorator.

5. Local Setup

To see the documentation on your local machine, ensure you have the library installed. Run: pip install drf-spectacular Ensure it's in our requirements.txt (I will handle this in the first PR).