如何使用Django API文档

DebugUsery
581 阅读3分钟

开始使用Django API文档

REST API文档是API开发过程中的一个重要步骤。文档使其他将使用该API的开发者有可能了解该API的工作原理。

记录API

在本教程中，我们将学习如何为我们的RESTful API端点添加文档。

前提条件

  1. 在你的电脑上安装了[Python]。
  2. 在你的电脑上安装了[Virtualenv]。
  3. [Python]和[Django]知识。

创建项目

在终端上执行下面的命令，为我们的项目创建一个工作目录。

$ mkdir documentation
$ cd documentation

现在我们已经创建了一个工作目录并改变了它的路径，通过执行下面的命令为该项目创建一个虚拟环境。

$ virtualenv venv
$ source venv/bin/activate

现在让我们把Django安装到我们的虚拟环境中，并通过执行下面的命令创建我们的Django项目。

$ (venv) pip install django
$ (venv) django-admin startproject django_todo

由于我们将使用DjangoRest框架、drf_yasg和coreapi，我们需要安装这些软件包。

执行下面的命令来安装DjangoRest框架、drf_yasg和coreapi。

$ pip install djangorestframework
$ pip install coreapi
$ pip install -U drf-yasg[validation]

Django将代码组织成应用程序，这使我们更容易编写代码，更容易维护。执行下面的命令，创建一个todo 应用程序，它将保存我们应用程序的源代码。

$ ./manage.py startapp todo

Django模型

在上面创建的todo 应用程序中，将下面的代码片断添加到models.py 文件中。模型是一个Python类，代表关系数据库中的一个表。Django将模型映射到数据库表。

class Todo(models.Model):
    title = models.CharField(max_length = 100)
    body = models.CharField(max_length = 100)
    is_completed = models.BooleanField(default=False)
    date_created = models.DateField(auto_created=True)
    last_modified = models.DateField(auto_now=True)

    def __str___(self):
        return self.title

Django序列化器

将数据从Python对象转换为JSON，反之亦然，是一项具有挑战性的任务。Django通过提供一个可以扩展的serializer 类来执行转换，从而简化了这个转换过程。

在todo 应用程序中创建一个名为serializers.py 的Python文件，并添加以下代码片段。

class TodoSerializer(serializers.ModelSerializer):
    class Meta:
        model = Todo
        fields = "__all__"

Django API视图

Django遵循模型视图模板（MVT）模式。视图持有对传入的HTTP请求采取行动的逻辑。

在todo 应用程序中的views.py 文件中，添加下面的代码片段。

from rest_framework.generics import ListAPIView
from rest_framework.generics import CreateAPIView
from rest_framework.generics import DestroyAPIView
from rest_framework.generics import UpdateAPIView
from todo.serializers import TodoSerializer
from todo.models import Todo

# Create your views here.
class ListTodoAPIView(ListAPIView):
    """Lists all todos from the database"""
    queryset = Todo.objects.all()
    serializer_class = TodoSerializer

class CreateTodoAPIView(CreateAPIView):
    """Creates a new todo"""
    queryset = Todo.objects.all()
    serializer_class = TodoSerializer

class UpdateTodoAPIView(UpdateAPIView):
    """Update the todo whose id has been passed through the request"""
    queryset = Todo.objects.all()
    serializer_class = TodoSerializer

class DeleteTodoAPIView(DestroyAPIView):
    """Deletes a todo whose id has been passed through the request"""
    queryset = Todo.objects.all()
    serializer_class = TodoSerializer

Django URL

为了与我们的应用程序进行通信，我们必须提供一个API端点URL，客户端可以在那里请求和提交数据。在todo 应用程序中，创建一个名为urls.py 的新文件，并添加下面的代码片段。

urlpatterns = [
    path("",views.ListTodoAPIView.as_view(),name="todo_list"),
    path("create/", views.CreateTodoAPIView.as_view(),name="todo_create"),
    path("update/<int:pk>/",views.UpdateTodoAPIView.as_view(),name="update_todo"),
    path("delete/<int:pk>/",views.DeleteTodoAPIView.as_view(),name="delete_todo")
]

在根项目urls.py 文件中，添加下面的代码片断，将我们的todo 应用程序的URL与根项目的URL进行配置。

# Swagger documentation setup
schema_view = get_schema_view(
    openapi.Info(
        title="Snippets API",
        default_version='v1',
        description="Test description",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="contact@snippets.local"),
        license=openapi.License(name="MIT License"),
    ),
    public=True,
    permission_classes=[permissions.AllowAny],
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/v1/todo/', include("todo.urls")),
    path('docs/', include_docs_urls(title='Todo Api')),
    url(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
    url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]

Django settings.py

settings.py 文件应该包含下面的配置。将我们之前安装的软件包添加到INSTALLED_APPS 应用程序字典中。

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent


SECRET_KEY = '9s^sq5s0pp*hd)%i2)*m3n--e-=)2tn&7i&c)o6z#l-m18jx4)'

DEBUG = True

ALLOWED_HOSTS = []


# Application definition

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'todo',
    'rest_framework',
    'coreapi', # Coreapi for coreapi documentation
    'drf_yasg', # drf_yasg fro Swagger documentation
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

ROOT_URLCONF = 'django_todo.urls'

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]
REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema'
}

WSGI_APPLICATION = 'django_todo.wsgi.application'


DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}


AUTH_PASSWORD_VALIDATORS = [
    {
        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
    },
]


LANGUAGE_CODE = 'en-us'

TIME_ZONE = 'UTC'

USE_I18N = True

USE_L10N = True

USE_TZ = True


STATIC_URL = '/static/'

测试文档

现在我们已经实现了为我们的API生成文档所需的代码，让我们来测试它。

注意：请确保应用程序正在运行。

Coreapi

在你的浏览器上，导航到http://127.0.0.1:8000/docs/ ，查看coreapi文档。

coreapi documentation

Swagger

在你的浏览器上，导航到http://127.0.0.1:8000/swagger/ ，查看Swagger文档。

Swagger documentation

Redoc

在你的浏览器上，导航到http://127.0.0.1:8000/redoc ，查看redoc文档。

redoc documentation

总结

现在你已经学会了如何记录Django RESTful API端点，请继续并为每个API端点文档添加描述性说明。

avatar
文章
阅读
粉丝