|
優(yōu)質(zhì)文章，第一時(shí)間送達(dá)！ 
近期推文： Python利用Django 構(gòu)建Rest Api: 快速入門教程
Python 3+Django 3 結(jié)合Vue.js框架構(gòu)建前后端分離Web開發(fā)平臺(tái)實(shí)戰(zhàn)
1. 前言當(dāng)接口開發(fā)完成，緊接著需要編寫接口文檔。傳統(tǒng)的接口文檔通常都是使用Word或者一些接口文檔管理平臺(tái)進(jìn)行編寫，但此類接口文檔維護(hù)更新比較麻煩，每次接口有變更，需要手動(dòng)修改接口文檔。在實(shí)際的工作中，經(jīng)常會(huì)遇到：“前端抱怨后端給的接口文檔與實(shí)際情況不一致。后端又覺得編寫及維護(hù)接口文檔會(huì)耗費(fèi)不少精力，經(jīng)常來(lái)不及更新”。為了解決這個(gè)問題，業(yè)界推出了一個(gè)Swagger框架來(lái)管理接口文檔，實(shí)現(xiàn)接口文檔的自動(dòng)更新。 采用Swagger框架來(lái)管理接口文檔，常用于在微服務(wù)架構(gòu)設(shè)計(jì)或者Java的后端服務(wù)工程中。這也造成了很多讀者誤認(rèn)為Swagger只是Java語(yǔ)言下的一個(gè)框架，其實(shí)并不是的，Swagger除了能應(yīng)用在Java語(yǔ)言的工程中，也同時(shí)適用于在其它語(yǔ)言下，比如Python。接下來(lái)，在本篇文章，介紹的就是基于Python3+Django3下，如何接入Swagger框架，并且實(shí)現(xiàn)Swagger接口文檔的自動(dòng)生成。 2. Swagger介紹Swagger：它是一款RESTFUL接口的文檔在線自動(dòng)生成+功能測(cè)試并集規(guī)范于一體的工具框架，可用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)?？傮w目標(biāo)是使客戶端和文件系統(tǒng)源代碼作為服務(wù)器以同樣的速度來(lái)更新。當(dāng)接口有變動(dòng)時(shí)，對(duì)應(yīng)的接口文檔也會(huì)自動(dòng)更新生成。
例如：接口測(cè)試站點(diǎn)（http:///#/），也是利用Swagger來(lái)生成接口文檔的。 Swagger優(yōu)勢(shì)：
1）Swagger可生成一個(gè)具有互動(dòng)性的API控制臺(tái)，開發(fā)者可快速學(xué)習(xí)和嘗試API
2）Swagger支持不同客戶端SDK代碼，用于不同平臺(tái)上（Java、Python、...）的實(shí)現(xiàn)
3）Swagger可在不同的平臺(tái)上從代碼注釋中自動(dòng)生成
4）Swagger社區(qū)活躍，里面有許多強(qiáng)悍的貢獻(xiàn)者 3. Django項(xiàng)目配置1、在開始之前，我們先創(chuàng)建一個(gè)項(xiàng)目操作目錄和隔離環(huán)境，具體操作如下： # 創(chuàng)建項(xiàng)目目錄mkdir django_swaggercd django_swagger
# 創(chuàng)建隔離開發(fā)環(huán)境python3 -m venv envsource env/bin/activate
2、安裝django相關(guān)庫(kù) (env) ? pip install django(env) ? pip install djangorestframework
3、創(chuàng)建django項(xiàng)目和app # 創(chuàng)建django項(xiàng)目和appdjango-admin startproject drf_swaggercd drf_swaggerdjango-admin startapp api
需要注意的是，本篇文章示例，是基于Python3及Django當(dāng)前最新庫(kù)來(lái)進(jìn)行的。
(env) ? pip list | grep djangoDjango 3.0.1django-crispy-forms 1.8.1django-formtools 2.2django-import-export 2.0django-reversion 3.0.5djangorestframework 3.11.0
到此，我們已經(jīng)準(zhǔn)備好了django基礎(chǔ)環(huán)境和生成好了項(xiàng)目結(jié)構(gòu)。 4. Django接入Swagger網(wǎng)上很多資料在介紹Django接入Swagger方法時(shí)，都是基于django-rest-swagger庫(kù)進(jìn)行講解的，都殊不知，從2019年6月份開始，官方已經(jīng)廢棄了該庫(kù)，在django 3.0中已經(jīng)不支持該庫(kù)了，取而代之的是全新的第三方drf-yasg庫(kù)。
GitHub地址：
https://github.com/marcgibbons/django-rest-swagger
所以本文也是基于drf-yasg庫(kù)來(lái)實(shí)現(xiàn)在Django3中接入Swagger框架的。 1、安裝drf-yasg庫(kù) GitHub項(xiàng)目地址： https://github.com/axnsan12/drf-yasg
2、修改項(xiàng)目settings.py文件，添加api和drf_yasg。
# Application definition
INSTALLED_APPS = [ 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', 'rest_framework', 'drf_yasg', 'api',]
3、修改api/models.py，此處定義了一個(gè)添加接口的model模型（為了方便演示）
from django.db import models
class APIInfo(models.Model): api_name = models.CharField(max_length=32, verbose_name="接口名稱", default="請(qǐng)輸入接口名稱") # 接口描述 api_describe = models.TextField(max_length=255, verbose_name="接口描述", default="請(qǐng)輸入接口描述") # 接口負(fù)責(zé)人 api_manager = models.CharField(max_length=11, verbose_name="接口負(fù)責(zé)人", default="請(qǐng)輸入接口負(fù)責(zé)人名字") # 創(chuàng)建時(shí)間 create_time = models.DateTimeField(auto_now_add=True, verbose_name="創(chuàng)建時(shí)間") # 修改時(shí)間 update_time = models.DateTimeField(auto_now=True, blank=True, null=True, verbose_name="修改時(shí)間") class Meta: db_table = 'api_info' # 設(shè)置表名，默認(rèn)表名是：應(yīng)用名稱_模型類名 # 帶有應(yīng)用名的表名太長(zhǎng)了 verbose_name = '接口列表' verbose_name_plural = "接口列表"
def __str__(self): return self.api_name
4、修改api/admin.py，將model注冊(cè)到后臺(tái)，方便在管理后臺(tái)添加接口記錄。
from django.contrib import adminfrom . models import APIInfo
admin.site.register(APIInfo)
5、新建api/serializers.py文件，代碼內(nèi)容如下: from rest_framework import serializersfrom api.models import APIInfo
class APIInfoSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = APIInfo fields = "__all__"
class APISerializer(serializers.ModelSerializer): class Meta: model = APIInfo fields = "__all__"
6、修改api/view.py視圖文件，并在類中，添加注釋如下所示（為了方便演示）：
from rest_framework import viewsetsfrom rest_framework import genericsfrom . import modelsfrom . import serializers
class APIList(generics.ListAPIView): """ 查看接口列表 """ queryset = models.APIInfo.objects.all() serializer_class = serializers.APISerializer
class APIDetail(generics.RetrieveAPIView): """ 查看接口詳細(xì) """ queryset = models.APIInfo.objects.all() serializer_class = serializers.APISerializer
class APIDetail(generics.RetrieveUpdateDestroyAPIView): """ 更新接口內(nèi)容 """ queryset = models.APIInfo.objects.all() serializer_class = serializers.APISerializer
class APIInfoViewSet(viewsets.ModelViewSet): """ retrieve: 返回一組（查）
list: 返回所有組（查）
create: 創(chuàng)建新組（增）
delete: 刪除現(xiàn)有的一組（刪）
partial_update: 更新現(xiàn)有組中的一個(gè)或多個(gè)字段（改：部分更改）
update: 更新一組（改：全部更改） """
queryset = models.APIInfo.objects.all() serializer_class = serializers.APIInfoSerializer
7、修改項(xiàng)目url.py文件，進(jìn)行路由配置。
from django.contrib import adminfrom django.conf import settingsfrom django.urls import path,includefrom rest_framework import routers, permissionsfrom drf_yasg.views import get_schema_viewfrom drf_yasg import openapi
from api import views
router = routers.DefaultRouter()router.register('api_info', views.APIInfoViewSet)
schema_view = get_schema_view( openapi.Info( title="測(cè)試工程API", default_version='v1.0', description="測(cè)試工程接口文檔", terms_of_service="https://www.cnblogs.com/jinjiangongzuoshi/", contact=openapi.Contact(email="狂師"), license=openapi.License(name="BSD License"), ), public=True, permission_classes=(permissions.AllowAny,),)
urlpatterns = [ path('admin/', admin.site.urls),
# 配置django-rest-framwork API路由 path('api/', include('api.urls')), path('api-auth/', include('rest_framework.urls', namespace='rest_framework')), # 配置drf-yasg路由 path('^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'), path('swagger', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'), path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]
5. 執(zhí)行數(shù)據(jù)同步、運(yùn)行1、上述一切配置完成后，開始進(jìn)行數(shù)據(jù)庫(kù)遷移、同步。 # 生成遷文件、執(zhí)行同步python manage.py makemigrationspython manage.py migrate
2、創(chuàng)建后臺(tái)管理員用戶
python manage.py createsuperuser
3、運(yùn)行服務(wù)
python manage.py runserver
6. 驗(yàn)證效果1、服務(wù)運(yùn)行起來(lái)后，默認(rèn)端口為8000，瀏覽器訪問http://127.0.0.1:8000/redoc/，可查看redoc ui，效果如下所示。 
2、點(diǎn)擊左側(cè)的api，展開各接口詳細(xì)如下所示。
PS: ReDoc 是另一個(gè) Swagger UI 工具。
3、繼續(xù)訪問http://127.0.0.1:8000/swagger，即可看到日常我們熟悉的Swagger接口文檔界面了。
4、Swagger除了可以即時(shí)生成接口文檔以外，還可以用于在線做一些接口功能測(cè)試，如下所示。
5、在Swagger中還可以查看到在model定義的各字段類型及參數(shù)說明。
到此，我們Django3接入Swagger已經(jīng)完成了，更多swagger的功能使用請(qǐng)讀者自行嘗試。
|
