Django框架之drf

一、接口文档

简介:

​ 接口文档通常是在前后端分离时,后端开发人员需要编写的文档,其内容是将接口的信息、地址和使用方法及其他注意事项告知前端开发人员及团队,目的是便于团队间的沟通、协作,降低团队合作成本

接口文档所需内容:

1、描述:
	对视图类/函数的功能及用法描述
2、地址:
	请求地址(url路由)
3、请求方式:
	功能的请求方式(例如:post、get)
4、请求编码格式:
	json、form-data、urlencode。。。
5、请求数据类型:(必填)
	字段的类型(例如:int、str、list)
6、返回格式案例:
	返回的数据的格式案例
7、返回字段解释:
	对每个字段的解释
8、错误码:
	公司内部定义的错误码

接口文档如何编写

1、使用word、md等文档编辑工具编写

2、使用第三方平台提供的专门用来编写API接口文档的工具(收费)

3、公司使用第三方开源的API接口文档代码搭建一个专门用于公司内部编写接口文档的网站(例如Yapi:-https://zhuanlan.zhihu.com/p/366025001

4、使用Django框架的drf所提供的文档自动生成工具:coreapi(本编文章重点所讲)

二、CoreAPI文档生成器

简介:

​ coreapi是drf框架提供的接口文档自动生成器,它仅限于在drf种使用,可根据我们编写的url路径和视图函数/类自动生成接口文档,支持注释和编辑

安装:

# cmd终端或pycharm中使用pip进行安装
pip3.8 install coreapi -i http://mirrors.aliyun.com/

1、使用方法

第一步:配置路由

# 导入模块:
from rest_framework.documentation import include_docs_urls

# 生成路由:
urlpatterns = [
    # 后缀名可以自定义,title为接口文档标题
    path('docs/', include_docs_urls(title='xxx项目接口文档')),
		]

第二步:在视图层的视图类代码下编写注释

# 在视图类代码下编写注释
    class BookView(ModelViewSet):
       '''
       list:查询所有图书 
       create:新增图书
       retrieve:查询单个图书
       update:更新图书
       destroy:删除图书
       '''
    	pass

第三步:在项目配置文件中进行配置

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

第四步:字段的注释及约束

help_text:字段名的注释

required:限制字段能不能为空(true/false)

# 方式一: 在模型表上添加
class Book(models.Model):
    name = models.CharField(max_length=32, help_text='书名')
    price = models.CharField(max_length=32, help_text='价格')
    author = models.ManyToManyField(to='Author', help_text='作者')
    
# 方式二:序列化类中添加(优先级高于模型表)
class BookSerializer(serializers.ModelSerializer):
    model = Book
        # 序列化的字段
        fields = ['pk', 'name']
        # 字段校验条件
        extra_kwargs = {
            'name': {'max_length': 32, 'help_text': '书名'}
       				 }
    # 在外部编写优先级高于extra_kwargs
    name = serializers.CharField(help_text='书名', required=False)

Django框架之drf:9、接口文档,coreapi的使用,JWT原理、介绍、快速使用、定制、认证

Django框架之drf:9、接口文档,coreapi的使用,JWT原理、介绍、快速使用、定制、认证

三、JWT

1、JWT原理及介绍

简介:

​ Json web token(JWT),就是web方向token的使用,它是在cookie、session和token中提升出来的技术,用于用户认证和签发。
​ JWP由三部分组成:头部(header)、荷载(payload)、签名(signature)

  • 头:header(存放基本信息的地方)
    • 声明类型、声明加密类型、公司信息
# 完整头部信息(json格式)
    {
      'typ': 'JWT',
      'alg': 'HS256'
    }
  
# 将头部进行base64加密(该加密是可以对称解密的),构成了第一部分
	eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
  • 荷载:payload(存放有效信息(或用户信息)
    • 过期时间、签发时间、用户ID、用户名字
# 荷载部分信息示例:
	{
    "sub": "1234567890",
    "name": "John Doe",
    "admin": true
	}
    
# 进行base64加密,得到JWT的第二部分
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9
  • 签名:signature
    • 这个部分需要base64加密后的header和base64加密后的payload使用.连接组成的字符串,然后通过header中声明的加密方式进行加盐secret组合加密,然后就构成了jwt的第三部分
# 完整的JWT
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

Django框架之drf:9、接口文档,coreapi的使用,JWT原理、介绍、快速使用、定制、认证

2、JWP快速使用

模块选择

1、djangorestframework-jwt
	# 已经停止维护,但可以用(本次所用)
    	
2、djangorestframework-simplejwt
	# 公司使用的较多,用法相对简单

使用步骤

djangorestframework-jwt默认自带auth表的登录功能(不用手动再写登录)

1、安装:
	pip3.8 install djangorestframework-jwt
    
2、快速签发token:(配合auth表使用)
	path('login/', obtain_jwt_token) # 配置路由
    
3、向路由发送请求(携带username,password)
	http://127.0.0.1:8000/login/

Django框架之drf:9、接口文档,coreapi的使用,JWT原理、介绍、快速使用、定制、认证

3、定制返回格式

​ 上面我们快速的使用了JWT,发现我们只需要在路由层进行配置就可以快速使用,这是因为jwt内置中已经编写了登录接口,但是返回的数据并不满足规范

定制格式:

1、在app下创建一个专门用于定制返回格式的py文件(jwt_response.py),在文件中写一个函数
	def jwt_response_payload_handler(token, user=None, request=None):
    return {
        'code': 100,
        'msg': '登录成功!',
        'user':user.username,
        'result': token
    }
    
2、在项目文件中进行配置
	JWT_AUTH = {
    	'JWT_RESPONSE_PAYLOAD_HANDLER': 'app01.utils.jwt_response_payload_handler',  
	}
    
3、使用postman测试,发现格式配置成功
	

Django框架之drf:9、接口文档,coreapi的使用,JWT原理、介绍、快速使用、定制、认证

4、JTW的认证类

第一步:

​ 通过上面的JWT的token的签发,就可以在需要使用认证的类中进行配置,后期在访问该视图时就会对jwt进行对比,验证通过后才能执行视图代码

# 在视图上添加认证类
class BookView(ModelViewSet):
    # jtw认证类
    authentication_classes = [JSONWebTokenAuthentication]

Django框架之drf:9、接口文档,coreapi的使用,JWT原理、介绍、快速使用、定制、认证

第二步:

​ 由上发现没有发送token但还是能正常访问配置后的视图,这是因为jwt的认证需要配合drf自带的权限类,【IsAuthenticated】,原因是jtw的认证原理是,如果带了token就会进行校验,校验错误就会被打回,如果没有带token就不会进行校验并直接通过,配合drf自带的权限类后会校验用户是否登录,这时没有登录的用户就会被打回,而校验用户是否登录的方式就从token中获取到登录用户,由此就可以解决用户不带token就能访问视图的问题

class BookView(ModelViewSet):
    # jtw认证类
    authentication_classes = [JSONWebTokenAuthentication]
    # drf自带权限类
    permission_classes = [IsAuthenticated]

Django框架之drf:9、接口文档,coreapi的使用,JWT原理、介绍、快速使用、定制、认证

第三步:

​ jtw的token存放在请求头中以key:value的方式存放,现在带上jwt的token尝试访问访问

  • jwt存放token的格式
    • key:Authorization
    • value:jwt+'空格'+有效的token值
# 请求头中添加键值对:
    Authorization:jwt eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VybmFtZSI6ImthbmdrYW5nIiwiZXhwIjoxNjc1OTQ4NjQwLCJlbWFpbCI6IiJ9.VbR5d_8ariu8Fj8muAoKhE7Sck3JnsPKe5wcIm-Z0As

Django框架之drf:9、接口文档,coreapi的使用,JWT原理、介绍、快速使用、定制、认证