DRF Spectacular

This page provides an overview of the DRF Spectacular integration in The Wall API.

Table of Contents

1. Overview
2. DRF Spectacular Configuration
   2.1 Basic Configuration
   2.2 Customizing the OpenAPI Schema
3. Folder Structure
4. OpenAPI Documentation
   4.1 Implementation Specifics
   4.2 References

1. Overview

DRF Spectacular is a powerful Python library for generating OpenAPI 3 schemas in Django REST Framework applications.

It is utilized in The Wall API to:

• Enable automatic API documentation, which can be explored using Swagger-UI and ReDoc.
• Reduce the need for manual documentation.
• Organize endpoints into categories.
• Provide dynamic OpenAPI schema customization.

---

2. DRF Spectacular Configuration

DRF Spectacular is integrated into the project via Django's settings.py.

2.1 Basic Configuration

• To enable the automatic OpenAPI documentation features, the following settings must be added:

  INSTALLED_APPS = [
      'drf_spectacular',
  ]
  
  REST_FRAMEWORK = {
      'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
  }

  ✔ This ensures that DRF Spectacular replaces DRF’s default schema generator with AutoSchema, allowing dynamic OpenAPI documentation generation.

Return to Top

2.2 Customizing the OpenAPI Schema

• The SPECTACULAR_SETTINGS dictionary in settings.py provides flexible customization.

  Toggle settings

  SPECTACULAR_SETTINGS = {
      'TITLE': 'The Wall API',
      'DESCRIPTION': 'Wall construction tracker.',
      'SERVE_INCLUDE_SCHEMA': False,
      'OAS_VERSION': '3.1.0',
      'TAGS': [
          {
              'name': openapi_messages.USER_MANAGEMENT_TAG,
              'description': openapi_messages.USER_MANAGEMENT_TAG_DESCRIPTION
          },
          {
              'name': openapi_messages.FILE_MANAGEMENT_TAG,
              'description': openapi_messages.FILE_MANAGEMENT_TAG_DESCRIPTION
          },
          {
              'name': openapi_messages.COST_AND_DAILY_ICE_AMOUNTS_TAG,
              'description': openapi_messages.COST_AND_DAILY_ICE_AMOUNTS_TAG_DESCRIPTION
          },
      ]
  }

  
  

• Key Configuration Options:

  Setting	Description
  TITLE	The API's title, displayed in Swagger-UI and ReDoc.
  DESCRIPTION	A short description of the API’s purpose.
  SERVE_INCLUDE_SCHEMA	Controls whether the schema itself is included in the API response.
  OAS_VERSION	Specifies the OpenAPI version.
  TAGS	Organizes endpoints.

  ✔ By defining tags, endpoints in Swagger-UI and ReDoc are grouped into logical categories, improving navigation and usability.

Return to Top

---

3. Folder structure

The DRF Spectacular-related files are located in the_wall_api/utils/open_api_schema_utils. The folder contains helper modules that extend the OpenAPI schema generation by adding custom documentation, parameters, and response structures.
Additionally, message_themes/openapi.py stores predefined OpenAPI messages for consistency.

Key Files and Their Purpose:

File / Folder	Description
the_wall_api/utils/
├── message_themes/
│    └── openapi.py	Predefined OpenAPI messages for documentation consistency.
└── open_api_schema_utils/	OpenAPI schema-related utilities.
├── auth_schema_extensions.py	Modifies TokenAuthentication schema with token usage details.
├── djoser_utils.py	Extends Djoser authentication views with OpenAPI schema documentation
├── open_api_examples.py	Stores example request/response bodies.
├── open_api_parameters.py	Defines reusable query and path parameters.
├── open_api_responses.py	Standardized API responses for schema definitions.
├── open_api_schemas.py	Defines a custom OpenAPI schema to enable file uploads in Swagger-UI.
├── request_serializers.py	Serializers used for documenting request bodies.
└── response_serializers.py	Serializers defining response formats.

✔ This structured approach ensures that the OpenAPI documentation is well-organized, customizable, and easily extendable as the API evolves.

Return to Top

---

4. OpenAPI Documentation

DRF Spectacular ensures a structured and detailed API representation in Swagger-UI and ReDoc. All views are documented using @extend_schema from drf_spectacular.utils, providing clear descriptions, request/response examples, and well-defined parameters.
Custom schema extensions improve authentication workflows and support file uploads within the API documentation.

4.1 Implementation Specifics

• Extended Djoser views - The authentication endpoints are subclassed to integrate @extend_schema, enriching the OpenAPI documentation with detailed request/response examples and custom descriptions.

• extend_schema annotations - All file management and cost & ice tracking views are also explicitly documented using @extend_schema.

• Tag-Based Organization - API endpoints are categorized into User Management, File Management, and Cost & Ice Tracking.

• Authentication schema customization - The auth_schema_extensions.py module overrides the TokenAuthentication security definition, providing additional details on how authentication tokens should be used in API requests.

• File upload schema definition – The open_api_schemas.py module is required for file uploads to appear in Swagger-UI. Without it, file input fields are not displayed in the documentation.

  • Defines the multipart/form-data schema, allowing Swagger-UI to properly render a file upload option.

  ✔ This schema ensures correct file upload representation in Swagger-UI, improving API usability.

Return to Top

4.2 References

• Detailed OpenAPI documentation: OpenAPI Documentation
• Swagger-UI quick guide: Swagger-UI Quick Guide

---

Back to: Docker - Production v2

Return to Top
DTS Index
Home Page

---