Django一分钟:DRF生成OpenAPI接口文档

DRF项目中如果想要自动生成API文档我们可以借助drf-spectacular这个库,drf-spectacular非常强大,它可以自动从DRF中提取信息,自动生成API文档,配置简单开箱即用,并且它对很多常用的第三方如:SimpleJWTdjango-filter等做了适配。

下面的示例中我们将创建一个一些接口,由django-filter实现过滤功能,并且使用drf-spectacular创建接口文档。

1. 下载依赖

shell 复制代码
pip install drf-spectacular[sidecar]
pip install django-filter

2. 配置settings.py

python 复制代码
# APP配置
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    "api.apps.BlogConfig",# 你的app

    'rest_framework',
    'drf_spectacular',
    'drf_spectacular_sidecar',
]

# DRF配置
REST_FRAMEWORK = {
    ...
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
    ...
}

# SPECTACULAR配置
SPECTACULAR_SETTINGS = {
    'TITLE': 'Your Project API',
    'DESCRIPTION': 'Your project description',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
}

3. 创建模型

python 复制代码
from django.db import models
from django_filters import rest_framework as filters
from rest_framework import serializers


class Order(models.Model):
    name = models.CharField(max_length=100)


class Product(models.Model):
    name = models.CharField(max_length=100)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    create_at = models.DateTimeField(auto_now_add=True)
    order = models.ForeignKey(Order, on_delete=models.CASCADE)

4. 创建过滤器

python 复制代码
class ProductFilter(filters.FilterSet):
    class Meta:
        model = Product
        fields = {
            'price': ['lt', 'gt'],
            'create_at': ['lt', 'gt'],
            'order__name': ['exact'],
        }

5. 创建序列化器

python 复制代码
class OrderSer(serializers.ModelSerializer):
    class Meta:
        model = Order
        fields = '__all__'

    def create(self, validated_data):
        return Order.objects.create(**validated_data)

    def update(self, instance, validated_data):
        instance.name = validated_data.get('name', instance.name)
        instance.save()
        return instance


class ProductReadSer(serializers.ModelSerializer):
    order = OrderSer(read_only=True)

    class Meta:
        model = Product
        fields = '__all__'


class ProductCreateSer(serializers.ModelSerializer):
    class Meta:
        model = Product
        fields = ['price', 'order']

    def create(self, validated_data):
        return Product.objects.create(**validated_data)

    def update(self, instance, validated_data):
        instance.price = validated_data.get('price', instance.price)
        instance.order = validated_data.get('order', instance.order)
        instance.save()
        return instance

6. 创建路由

python 复制代码
from django.contrib import admin
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView
from api.views import OrderViewSet, ProductReadViewSet, ProductCreateViewSet
router = DefaultRouter()
router.register(r'orders', OrderViewSet)
router.register(r'products/read', ProductReadViewSet, basename='product-read')
router.register(r'products/create', ProductCreateViewSet, basename='product-create')

# 后台管理
urlpatterns = [
    path('admin/', admin.site.urls),
]

# API接口
urlpatterns += [
    path('api/', include(router.urls)),
]

# API文档
urlpatterns += [
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

7. 数据库迁移

shell 复制代码
python manage.py makemigrations XXX
python manage.py migrate

8. 使用示例

启动项目打开我们配置的文档地址可以看到注册到路由中的接口其文档已经被自动创建好了。

配置了过滤器的接口也在文档中有所反映:

相关参考文档地址

相关推荐
小蒜学长20 分钟前
springboot餐厅信息管理系统设计(代码+数据库+LW)
java·数据库·spring boot·后端
Justin_1923 分钟前
mysql数据库高级特性(一)
数据库·mysql
邂逅you1 小时前
用python操作mysql之pymysql库基本操作
数据库·python·mysql
心 一1 小时前
接口安全测试实战:从数据库错误泄露看如何构建安全防线
数据库·安全
点灯小铭1 小时前
基于单片机的PID调节脉动真空灭菌器上位机远程监控设计
数据库·单片机·嵌入式硬件·毕业设计·课程设计
合作小小程序员小小店1 小时前
web开发,学院培养计划系统,基于Python,FlaskWeb,Mysql数据库
后端·python·mysql·django·web app
小高Baby@1 小时前
Redis Key的设计
数据库·redis·缓存
q_19132846952 小时前
基于RuoYi框架+Mysql的汽车进销存后台管理系统
数据库·vue.js·spring boot·mysql·汽车·个人开发·若依
wuyunhang1234562 小时前
MySQL----锁
数据库·mysql
悟能不能悟3 小时前
springboot在DTO使用service,怎么写
java·数据库·spring boot