Bài 10.3: API Versioning & Documentation - Phần 3 - drf-spectacular

**Series Navigation:** - [Bài 10.1: API Versioning](./010-api-versioning-documentation.md) - [Bài 10.2: OpenAPI & Swagger](./010-api-versioning-documentation-part2.md) - **Bài 10.3 (bài này): drf-spectacular** 👈 - [Bài 10.4: Advanced Documentation](./010-api-versioning-documentation-part4.md)

Mục Tiêu Bài 10.3

Sau khi hoàn thành Bài 10.3 này, bạn sẽ:

✅ Install and configure drf-spectacular
✅ Generate OpenAPI 3.0 schemas
✅ Customize schema generation
✅ Use Swagger UI & ReDoc
✅ Handle versioning
✅ Advanced schema features

Why drf-spectacular?

Problems with drf-yasg

drf-yasg has some limitations:

⚠️ OpenAPI 2.0 (Swagger 2.0) by default
⚠️ Limited OpenAPI 3.0 support
⚠️ Not actively maintained
⚠️ Complex customization

Benefits of drf-spectacular

drf-spectacular offers:

✅ Full OpenAPI 3.0 support
✅ Actively maintained
✅ Better type inference
✅ Cleaner API
✅ Better customization
✅ Automatic component detection
✅ Better serializer introspection

Recommendation: Use drf-spectacular for new projects.

Installation & Setup

Installation

pip install drf-spectacular

Basic Configuration

# settings.pyINSTALLED_APPS = [    # ...    'rest_framework',    'drf_spectacular',] REST_FRAMEWORK = {    # Use drf-spectacular schema class    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',} # drf-spectacular settingsSPECTACULAR_SETTINGS = {    'TITLE': 'My API',    'DESCRIPTION': 'API for managing articles, users, and more',    'VERSION': '1.0.0',    'SERVE_INCLUDE_SCHEMA': False,}

URL Configuration

# urls.pyfrom django.urls import path, includefrom drf_spectacular.views import (    SpectacularAPIView,    SpectacularRedocView,    SpectacularSwaggerView,) urlpatterns = [    # Your API endpoints    path('api/', include('myapp.urls')),        # OpenAPI schema    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),        # Swagger UI    path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),        # ReDoc    path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),]

Access documentation:

http://localhost:8000/api/schema/            # OpenAPI schema (JSON)http://localhost:8000/api/schema/swagger-ui/ # Swagger UIhttp://localhost:8000/api/schema/redoc/      # ReDoc

Basic Schema Generation

Auto-Generated Schema

# views.pyfrom rest_framework import viewsetsfrom .models import Articlefrom .serializers import ArticleSerializer class ArticleViewSet(viewsets.ModelViewSet):    """    ViewSet for managing articles.        Provides CRUD operations for articles with filtering and search capabilities.    """    queryset = Article.objects.all()    serializer_class = ArticleSerializer

drf-spectacular automatically generates:

✅ All CRUD endpoints
✅ Request/response schemas
✅ Query parameters from filters
✅ Pagination parameters

View Generated Schema

# Generate schema filepython manage.py spectacular --file schema.yml # Or download from browsercurl http://localhost:8000/api/schema/ > schema.yml

Customizing Endpoints

@extend_schema Decorator

# views.pyfrom drf_spectacular.utils import extend_schema, OpenApiParameter, OpenApiExamplefrom rest_framework import viewsets class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()    serializer_class = ArticleSerializer        @extend_schema(        summary="List all articles",        description="Returns a paginated list of articles with optional filtering",        parameters=[            OpenApiParameter(                name='status',                type=str,                enum=['draft', 'published', 'archived'],                description='Filter articles by publication status',            ),            OpenApiParameter(                name='search',                type=str,                description='Search in title and content',            ),        ],        responses={200: ArticleSerializer(many=True)},        tags=['Articles'],    )    def list(self, request, *args, **kwargs):        """Get list of articles"""        return super().list(request, *args, **kwargs)        @extend_schema(        summary="Create article",        description="Create a new article. Authentication required.",        request=ArticleSerializer,        responses={            201: ArticleSerializer,            400: OpenApiExample(                'Validation Error',                value={'title': ['This field is required']},            ),        },        tags=['Articles'],    )    def create(self, request, *args, **kwargs):        """Create new article"""        return super().create(request, *args, **kwargs)

Custom Actions

from rest_framework.decorators import actionfrom rest_framework.response import Responsefrom drf_spectacular.utils import extend_schema class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()    serializer_class = ArticleSerializer        @extend_schema(        summary="Publish article",        description="Change article status from draft to published",        request=None,        responses={            200: ArticleSerializer,            400: OpenApiExample(                'Already Published',                value={'error': 'Article is already published'}            ),        },        tags=['Articles', 'Actions'],    )    @action(detail=True, methods=['post'])    def publish(self, request, pk=None):        """Publish article"""        article = self.get_object()                if article.status == 'published':            return Response(                {'error': 'Article is already published'},                status=400            )                article.status = 'published'        article.save()                serializer = self.get_serializer(article)        return Response(serializer.data)

Request/Response Examples

from drf_spectacular.utils import extend_schema, OpenApiExample class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()    serializer_class = ArticleSerializer        @extend_schema(        summary="Create article",        request=ArticleSerializer,        examples=[            OpenApiExample(                'Basic Article',                value={                    'title': 'Getting Started with Django',                    'content': 'Django is a powerful web framework...',                    'status': 'draft'                },                request_only=True,            ),            OpenApiExample(                'Published Article',                value={                    'title': 'Advanced Django Techniques',                    'content': 'Learn advanced Django patterns...',                    'status': 'published'                },                request_only=True,            ),        ],        responses={            201: OpenApiExample(                'Created Article',                value={                    'id': 1,                    'title': 'Getting Started with Django',                    'content': 'Django is a powerful web framework...',                    'status': 'draft',                    'author': {'id': 5, 'username': 'john'},                    'views': 0,                    'likes': 0,                    'created_at': '2024-01-01T00:00:00Z'                },                response_only=True,            ),        },        tags=['Articles'],    )    def create(self, request, *args, **kwargs):        return super().create(request, *args, **kwargs)

Serializer Schema

Field Documentation

# serializers.pyfrom rest_framework import serializersfrom drf_spectacular.utils import extend_schema_field class ArticleSerializer(serializers.ModelSerializer):    author = serializers.SerializerMethodField(        help_text="Author information including ID, username, and email"    )        class Meta:        model = Article        fields = [            'id', 'title', 'content', 'author', 'status',            'views', 'likes', 'created_at', 'updated_at'        ]        extra_kwargs = {            'title': {                'help_text': 'Article title (max 200 characters)',                'max_length': 200,            },            'content': {                'help_text': 'Article content in Markdown format',            },            'status': {                'help_text': 'Publication status: draft, published, or archived',            },        }        @extend_schema_field({        'type': 'object',        'properties': {            'id': {'type': 'integer'},            'username': {'type': 'string'},            'email': {'type': 'string', 'format': 'email'},        }    })    def get_author(self, obj):        """Get author details"""        return {            'id': obj.author.id,            'username': obj.author.username,            'email': obj.author.email,        }

Polymorphic Serializers

from drf_spectacular.utils import extend_schema_serializer, PolymorphicProxySerializer class TextContentSerializer(serializers.Serializer):    type = serializers.CharField(default='text')    text = serializers.CharField() class ImageContentSerializer(serializers.Serializer):    type = serializers.CharField(default='image')    url = serializers.URLField()    caption = serializers.CharField(required=False) class VideoContentSerializer(serializers.Serializer):    type = serializers.CharField(default='video')    url = serializers.URLField()    thumbnail = serializers.URLField(required=False) # Document polymorphic field@extend_schema_serializer(    examples=[        OpenApiExample(            'Text Content',            value={'type': 'text', 'text': 'Sample text content'}        ),        OpenApiExample(            'Image Content',            value={'type': 'image', 'url': 'https://example.com/image.jpg', 'caption': 'An image'}        ),    ])class ArticleContentSerializer(serializers.Serializer):    content_type = serializers.ChoiceField(choices=['text', 'image', 'video'])    content = serializers.JSONField() # Or use PolymorphicProxySerializerclass ArticleViewSet(viewsets.ModelViewSet):    @extend_schema(        request=PolymorphicProxySerializer(            component_name='ArticleContent',            serializers=[                TextContentSerializer,                ImageContentSerializer,                VideoContentSerializer,            ],            resource_type_field_name='type',        )    )    def create(self, request, *args, **kwargs):        return super().create(request, *args, **kwargs)

Comprehensive Settings

SPECTACULAR_SETTINGS

# settings.pySPECTACULAR_SETTINGS = {    # Basic metadata    'TITLE': 'My API',    'DESCRIPTION': 'Comprehensive API documentation',    'VERSION': '1.0.0',    'CONTACT': {        'name': 'API Support',        'email': 'support@example.com',        'url': 'https://www.example.com/support',    },    'LICENSE': {        'name': 'MIT License',        'url': 'https://opensource.org/licenses/MIT',    },        # Server configuration    'SERVERS': [        {'url': 'https://api.example.com', 'description': 'Production server'},        {'url': 'https://staging.example.com', 'description': 'Staging server'},        {'url': 'http://localhost:8000', 'description': 'Development server'},    ],        # Schema generation    'SERVE_INCLUDE_SCHEMA': False,    'SERVE_PERMISSIONS': ['rest_framework.permissions.AllowAny'],        # Component settings    'COMPONENT_SPLIT_REQUEST': True,  # Split components for request/response    'COMPONENT_NO_READ_ONLY_REQUIRED': True,        # Authentication    'SECURITY': [{'bearerAuth': []}],    'APPEND_COMPONENTS': {        'securitySchemes': {            'bearerAuth': {                'type': 'http',                'scheme': 'bearer',                'bearerFormat': 'JWT',            }        }    },        # Schema preprocessing    'PREPROCESSING_HOOKS': [        'drf_spectacular.hooks.preprocess_exclude_path_format',    ],        # Postprocessing    'POSTPROCESSING_HOOKS': [        'drf_spectacular.contrib.djangorestframework_camel_case.camelize_serializer_fields',    ],        # Extensions    'SCHEMA_PATH_PREFIX': '/api/',    'SCHEMA_PATH_PREFIX_TRIM': True,        # Tags    'TAGS': [        {'name': 'Articles', 'description': 'Article management endpoints'},        {'name': 'Users', 'description': 'User management endpoints'},        {'name': 'Comments', 'description': 'Comment management endpoints'},    ],        # Enum options    'ENUM_NAME_OVERRIDES': {        'StatusEnum': 'myapp.models.Article.status',    },        # Swagger UI settings    'SWAGGER_UI_SETTINGS': {        'deepLinking': True,        'persistAuthorization': True,        'displayOperationId': True,    },        # ReDoc settings    'REDOC_UI_SETTINGS': {        'hideDownloadButton': False,        'expandResponses': '200,201',    },}

API Versioning with drf-spectacular

URL Path Versioning

# settings.pyREST_FRAMEWORK = {    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',    'DEFAULT_VERSION': 'v1',    'ALLOWED_VERSIONS': ['v1', 'v2'],} SPECTACULAR_SETTINGS = {    'TITLE': 'My API',    'VERSION': '1.0.0',    'SCHEMA_PATH_PREFIX': '/api/',} # urls.pyfrom django.urls import path, includefrom rest_framework.routers import DefaultRouter # V1 URLsrouter_v1 = DefaultRouter()router_v1.register('articles', ArticleViewSetV1, basename='article-v1') # V2 URLsrouter_v2 = DefaultRouter()router_v2.register('articles', ArticleViewSetV2, basename='article-v2') urlpatterns = [    path('api/v1/', include(router_v1.urls)),    path('api/v2/', include(router_v2.urls)),        # Schema for each version    path('api/v1/schema/', SpectacularAPIView.as_view(urlconf='myapp.urls_v1'), name='schema-v1'),    path('api/v2/schema/', SpectacularAPIView.as_view(urlconf='myapp.urls_v2'), name='schema-v2'),        # Swagger UI for each version    path('api/v1/docs/', SpectacularSwaggerView.as_view(url_name='schema-v1'), name='swagger-v1'),    path('api/v2/docs/', SpectacularSwaggerView.as_view(url_name='schema-v2'), name='swagger-v2'),]

Version-Specific Serializers

# serializers.pyclass ArticleSerializerV1(serializers.ModelSerializer):    """V1 serializer - simple fields"""    class Meta:        model = Article        fields = ['id', 'title', 'content', 'created_at'] class ArticleSerializerV2(serializers.ModelSerializer):    """V2 serializer - includes author and stats"""    author = serializers.SerializerMethodField()    stats = serializers.SerializerMethodField()        class Meta:        model = Article        fields = ['id', 'title', 'content', 'author', 'stats', 'created_at']        def get_author(self, obj):        return {            'id': obj.author.id,            'username': obj.author.username        }        def get_stats(self, obj):        return {            'views': obj.views,            'likes': obj.likes        } # views.pyfrom drf_spectacular.utils import extend_schema @extend_schema(tags=['Articles V1'])class ArticleViewSetV1(viewsets.ModelViewSet):    """V1 Article API - Basic functionality"""    queryset = Article.objects.all()    serializer_class = ArticleSerializerV1 @extend_schema(tags=['Articles V2'])class ArticleViewSetV2(viewsets.ModelViewSet):    """V2 Article API - Enhanced with author and stats"""    queryset = Article.objects.select_related('author').all()    serializer_class = ArticleSerializerV2

Advanced Features

Custom Schema Hooks

# hooks.pydef custom_preprocessing_hook(endpoints):    """    Custom preprocessing to modify schema before generation    """    # Filter out certain endpoints    filtered = []    for path, path_regex, method, callback in endpoints:        # Skip internal endpoints        if not path.startswith('/internal/'):            filtered.append((path, path_regex, method, callback))    return filtered def custom_postprocessing_hook(result, generator, request, public):    """    Custom postprocessing to modify generated schema    """    # Add custom fields to schema    result['info']['x-custom-field'] = 'custom-value'        # Add external documentation    result['externalDocs'] = {        'description': 'Find more info here',        'url': 'https://docs.example.com'    }        return result # settings.pySPECTACULAR_SETTINGS = {    'PREPROCESSING_HOOKS': [        'myapp.hooks.custom_preprocessing_hook',    ],    'POSTPROCESSING_HOOKS': [        'myapp.hooks.custom_postprocessing_hook',    ],}

Custom Operation IDs

# settings.pySPECTACULAR_SETTINGS = {    'OPERATION_ID_FUNCTION': 'myapp.utils.custom_operation_id',} # utils.pydef custom_operation_id(method, path, action=None):    """    Generate custom operation IDs    """    # Extract resource name from path    parts = path.strip('/').split('/')    resource = parts[-1] if parts else 'unknown'        # Build operation ID    if action:        return f"{resource}_{action}"    else:        method_map = {            'GET': 'list' if '{' not in path else 'retrieve',            'POST': 'create',            'PUT': 'update',            'PATCH': 'partial_update',            'DELETE': 'destroy',        }        operation = method_map.get(method, method.lower())        return f"{resource}_{operation}"

Schema Extensions

from drf_spectacular.extensions import (    OpenApiAuthenticationExtension,    OpenApiFilterExtension,) class CustomAuthExtension(OpenApiAuthenticationExtension):    target_class = 'myapp.authentication.CustomAuthentication'    name = 'CustomAuth'        def get_security_definition(self, auto_schema):        return {            'type': 'apiKey',            'in': 'header',            'name': 'X-API-Key',            'description': 'Custom API key authentication'        } class CustomFilterExtension(OpenApiFilterExtension):    target_class = 'myapp.filters.CustomFilter'        def get_schema_operation_parameters(self, auto_schema, *args, **kwargs):        return [            {                'name': 'custom_filter',                'in': 'query',                'required': False,                'description': 'Custom filtering parameter',                'schema': {'type': 'string'},            }        ]

Testing Schema

Validate Schema

# Generate and validate schemapython manage.py spectacular --validate --file schema.yml # Check for errorspython manage.py spectacular --check

Schema in Tests

# tests.pyfrom django.test import TestCasefrom rest_framework.test import APIClientfrom drf_spectacular.validation import validate_schema class SchemaTestCase(TestCase):    def test_schema_generation(self):        """Test that schema generates without errors"""        client = APIClient()        response = client.get('/api/schema/')                self.assertEqual(response.status_code, 200)                # Validate schema        schema = response.json()        errors = validate_schema(schema)        self.assertEqual(len(errors), 0, f"Schema validation errors: {errors}")        def test_schema_contains_endpoints(self):        """Test that schema contains expected endpoints"""        client = APIClient()        response = client.get('/api/schema/')        schema = response.json()                paths = schema['paths']                # Check articles endpoints        self.assertIn('/api/articles/', paths)        self.assertIn('/api/articles/{id}/', paths)                # Check methods        self.assertIn('get', paths['/api/articles/'])        self.assertIn('post', paths['/api/articles/'])

Complete Example

# models.pyfrom django.db import modelsfrom django.contrib.auth.models import User class Article(models.Model):    STATUS_CHOICES = [        ('draft', 'Draft'),        ('published', 'Published'),        ('archived', 'Archived'),    ]        title = models.CharField(max_length=200)    content = models.TextField()    author = models.ForeignKey(User, on_delete=models.CASCADE)    status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='draft')    views = models.IntegerField(default=0)    likes = models.IntegerField(default=0)    created_at = models.DateTimeField(auto_now_add=True)    updated_at = models.DateTimeField(auto_now=True) # serializers.pyfrom rest_framework import serializersfrom drf_spectacular.utils import extend_schema_field class AuthorSerializer(serializers.Serializer):    id = serializers.IntegerField()    username = serializers.CharField()    email = serializers.EmailField() class ArticleSerializer(serializers.ModelSerializer):    author = serializers.SerializerMethodField(        help_text="Author information"    )        class Meta:        model = Article        fields = [            'id', 'title', 'content', 'author', 'status',            'views', 'likes', 'created_at', 'updated_at'        ]        read_only_fields = ['id', 'views', 'likes', 'created_at', 'updated_at']        extra_kwargs = {            'title': {'help_text': 'Article title (max 200 characters)'},            'content': {'help_text': 'Article content in Markdown'},            'status': {'help_text': 'Publication status'},        }        @extend_schema_field(AuthorSerializer)    def get_author(self, obj):        return {            'id': obj.author.id,            'username': obj.author.username,            'email': obj.author.email,        } # views.pyfrom rest_framework import viewsets, filtersfrom rest_framework.decorators import actionfrom rest_framework.response import Responsefrom django_filters.rest_framework import DjangoFilterBackendfrom drf_spectacular.utils import extend_schema, OpenApiParameter, OpenApiExample class ArticleViewSet(viewsets.ModelViewSet):    """    ViewSet for managing articles.        Provides full CRUD operations with filtering, search, and custom actions.    """    queryset = Article.objects.select_related('author').all()    serializer_class = ArticleSerializer    filter_backends = [DjangoFilterBackend, filters.SearchFilter, filters.OrderingFilter]    filterset_fields = ['status', 'author']    search_fields = ['title', 'content']    ordering_fields = ['created_at', 'views', 'likes']        @extend_schema(        summary="List articles",        description="Get paginated list of articles with filtering and search",        parameters=[            OpenApiParameter('status', enum=['draft', 'published', 'archived']),            OpenApiParameter('author', type=int),            OpenApiParameter('search', type=str),            OpenApiParameter('ordering', enum=['created_at', '-created_at', 'views', '-views']),        ],        responses={200: ArticleSerializer(many=True)},        tags=['Articles'],    )    def list(self, request, *args, **kwargs):        return super().list(request, *args, **kwargs)        @extend_schema(        summary="Create article",        description="Create new article (authentication required)",        request=ArticleSerializer,        examples=[            OpenApiExample(                'Draft Article',                value={'title': 'My Article', 'content': 'Content...', 'status': 'draft'}            ),        ],        responses={201: ArticleSerializer},        tags=['Articles'],    )    def create(self, request, *args, **kwargs):        return super().create(request, *args, **kwargs)        @extend_schema(        summary="Publish article",        description="Change article status to published",        request=None,        responses={            200: ArticleSerializer,            400: OpenApiExample('Error', value={'error': 'Already published'}),        },        tags=['Articles', 'Actions'],    )    @action(detail=True, methods=['post'])    def publish(self, request, pk=None):        article = self.get_object()        article.status = 'published'        article.save()        serializer = self.get_serializer(article)        return Response(serializer.data) # settings.pyINSTALLED_APPS = [    # ...    'rest_framework',    'drf_spectacular',    'django_filters',] REST_FRAMEWORK = {    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',} SPECTACULAR_SETTINGS = {    'TITLE': 'Articles API',    'DESCRIPTION': 'Comprehensive API for article management',    'VERSION': '1.0.0',    'SERVE_INCLUDE_SCHEMA': False,    'COMPONENT_SPLIT_REQUEST': True,    'SECURITY': [{'bearerAuth': []}],    'APPEND_COMPONENTS': {        'securitySchemes': {            'bearerAuth': {                'type': 'http',                'scheme': 'bearer',                'bearerFormat': 'JWT',            }        }    },    'TAGS': [        {'name': 'Articles', 'description': 'Article management'},        {'name': 'Actions', 'description': 'Custom actions'},    ],} # urls.pyfrom django.urls import path, includefrom rest_framework.routers import DefaultRouterfrom drf_spectacular.views import (    SpectacularAPIView,    SpectacularSwaggerView,    SpectacularRedocView,) router = DefaultRouter()router.register('articles', ArticleViewSet, basename='article') urlpatterns = [    path('api/', include(router.urls)),    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),    path('api/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),]

Tóm Tắt Bài 10.3

Trong Bài 10.3 này, bạn đã học:

✅ drf-spectacular Basics:

Why use drf-spectacular
Installation and setup
Basic configuration

✅ Schema Generation:

Auto-generated schemas
Customizing endpoints
Request/response examples

✅ Advanced Features:

Serializer documentation
Polymorphic serializers
Custom schema hooks
Schema extensions

✅ API Versioning:

URL path versioning
Version-specific serializers
Versioned documentation

✅ Testing & Validation:

Schema validation
Testing schemas
Complete examples

Next Steps

Trong Bài 10.4, bạn sẽ học:

Advanced documentation techniques
Custom schema generation
Documenting complex endpoints
Code samples and examples
Documentation hosting
Best practices

Navigation:

#openapi

API Versioning & Documentation - Phần 2 - OpenAPI & Swagger

API Versioning & Documentation - Phần 3 - drf-spectacular