Ubuntu下Django与RestFramework搭建API及文档返回JSON全流程

小石头

发布时间：2026-10-14 | 4人浏览过

原创

本文介绍在Ubuntu 18.04环境下，使用Django和RestFramework快速构建API接口的完整流程。涵盖项目创建、模型定义、序列化配置、路由设置及后台管理，并演示如何通过Postman测试接口获取JSON数据，同时自动生成可视化的API文档。

环境准备与项目初始化

本教程基于Ubuntu 18.04 x64系统环境进行演示。

相关示例代码已托管于GitHub：https://github.com/xingjidemimi/DjangoAPI.git。

环境安装


pip install django==2.1.5
pip install djangorestframework # rest api
pip install coreapi pygments markdown # 自动化接口文档

API示例构建

首先创建Django项目。

在项目根目录下执行命令：django-admin startproject DjangoAPI。

接着创建应用模块。

进入项目目录：cd DjangoAPI。

执行命令创建名为apiApp的应用：python manage.py startapp apiApp。

核心代码配置与模型定义

项目代码配置

修改settings.py文件，将新创建的应用注册到配置中。


INSTALLED_APPS = [
 'django.contrib.admin',
 'django.contrib.auth',
 'django.contrib.contenttypes',
 'django.contrib.sessions',
 'django.contrib.messages',
 'django.contrib.staticfiles',
 'rest_framework', # 添加rest_framework应用
 'apiApp', # 添加apiApp应用
]

执行数据库迁移操作。

运行命令：python manage.py migrate。

创建超级管理员账户，系统会提示依次输入用户名（如ubuntu）、邮箱（如ubuntu@ubuntu.ubuntu）以及密码（如ubuntu123456）。

执行命令：python manage.py createsuperuser。

修改/api/models.py文件，定义数据库模型。


from django.db import models

class Test(models.Model):
 name = models.CharField(u'姓名', max_length=100, default='no_name')
 sex = models.CharField(u'性别', max_length=10, default='male')
 age = models.CharField(u'年龄', max_length=3, default='0')

 def __unicode__(self):
  return '%d: %s' % (self.pk, self.name)

模型创建完成后，需执行以下命令：

python manage.py makemigrations # 生成数据库迁移文件。

python manage.py migrate # 执行数据库迁移。

修改/api/admin.py文件，编写后台管理相关的代码。


from django.contrib import admin
from apiApp.models import Test
# Register your models here.

@admin.register(Test)
class BlogTypeAdmin(admin.ModelAdmin):
 list_display = ('pk', 'name') # 在后台列表下显示的字段

服务启动与接口测试

启动项目服务。

执行命令：python manage.py runserver。

若终端显示类似以下信息，则表明服务启动成功：


System check identified no issues (0 silenced).
January 23, 2019 - 08:28:09
Django version 2.1.5, using settings 'DjangoAPI.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

在浏览器中访问以下地址：

http://127.0.0.1:8000/ # 此时应看到Django默认的成功界面。

http://127.0.0.1:8000/admin # 可进入后台管理系统。

接下来对模型类进行序列化，在/api/目录下创建serializers.py文件，用于返回JSON格式的数据。


from rest_framework import serializers
from apiApp.models import Test

class TestSerializers(serializers.ModelSerializer):
 class Meta:
  model = Test # 指定的模型类
  fields = ('pk', 'name', 'sex', 'age',) # 需要序列化的属性

修改/api/views.py文件，定义视图逻辑。


from django.shortcuts import render
from rest_framework import viewsets
from apiApp.models import Test
from apiApp.serializers import TestSerializers


class TestViewSet(viewsets.ModelViewSet):
 # 指定结果集并设置排序
 queryset = Test.objects.all().order_by('-pk')
 # 指定序列化的类
 serializer_class = TestSerializers

修改根目录下的urls.py文件，配置主路由规则。


from django.contrib import admin
from django.urls import path, include

urlpatterns = [
 path('admin/', admin.site.urls),
 path('', include('apiApp.urls')), # 添加应用的路由地址
]

在/api/目录下创建urls.py文件，配置应用级别的路由。


from django.conf.urls import include
from django.urls import path
from rest_framework import routers
from apiApp import views
from rest_framework.documentation import include_docs_urls

API_TITLE = 'API Documents'
API_DESCRIPTION = 'API Information'


# 定义路由地址
route = routers.DefaultRouter()

# 注册新的路由地址
route.register(r'test', views.TestViewSet)

# 注册上一级的路由地址并添加
urlpatterns = [
 path('', include(route.urls)),
 # 接口文档路由
 path(r'docs/', include_docs_urls(title=API_TITLE, description=API_DESCRIPTION, authentication_classes=[], permission_classes=[]))
]

再次运行项目服务。