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

Django框架之drf
一、接口文档
二、CoreAPI文档生成器
- 1、使用方法
三、JWT

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原理、介绍、快速使用、定制、认证

三、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原理、介绍、快速使用、定制、认证