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