DRF - coreapi自动生成接口文档、JWT

目录

• 1 接口文档
  • 1.什么是接口文档
  • 2.接口文档的编写方式
  • 3.使用coreapi自动生成接口文档步骤
    • （1）安装coreapi
    • （2）配置路由
    • （3）文档说明文字：在视图类，方法上写注释即可
    • （4）配置文件中配置自动生成文档
    • （5）文档访问地址
  • 4.接口文档详细内容
• 2.JWT介绍和原理
  • 1.Cookie、session、Token的发展史
  • 2.JWT简介
  • 3.构成
• 3.JWT的组成部分
  • • header
    • payload
    • signature
• 4.JWT的使用
• 5.定制返回格式
• 6.JWT的认证类

1 接口文档

1.什么是接口文档

前后端分类的项目需要接口文档

-前端：

• 根据接口写app，pc，小程序

-后端：

• 不同功能的路由如
• 发送请求的方式
• 需要提供的数据名称
• 编码方式
• 返回方式

如：

路由：`/api/v1/login/`
请求方式：post
数据名称：username，password
编码方式：json
返回格式：{'code':100,'msg':'登录成功'}

2.接口文档的编写方式

• 1 自己编写

  使用word、md编写接口文档

• 2 使用第三方平台

  收费编写接口文档(非常多)

  如：https://www.showdoc.com.cn/item/index

• 3 公司自己使用第三方开源搭建

  自己搭建的方式参考：https://zhuanlan.zhihu.com/p/366025001

  如：YApi

• 4 使用drf的自动生成接口文档

  （1）官方推荐使用drf-yasg，底层使用swagger

  （2）coreapi

3.使用coreapi自动生成接口文档步骤

（1）安装coreapi

pip3 install coreapi -i https://pypi.tuna.tsinghua.edu.cn/simple  

（2）配置路由

导入接口文档路由

from rest_framework.documentation import include_docs_urls
urlpatterns = [
    path('docs/', include_docs_urls(title='图书管理API')),
]

（3）文档说明文字：在视图类，方法上写注释即可

• 在类上加注释

class BookView(ModelViewSet):
    """
    list:
    查询所有图书

    creat：
    新增图书信息

    retrieve：
    查询单个图书信息

    update:
    修改图书信息

    destroy：
    删除图书信息
    """
    queryset = Book.objects.all()
    serializer_class = BookSerializer

• 在类的方法上加注释

class BookView(ViewSetMixin, APIView):
    """
    list:
    查询所有图书信息
    """
    ...

• 在序列化类或表模型的字段上加参数

help_text required

class Book(models.Model):
    """图书表"""
    name = models.CharField(max_length=32, help_text="图书名")
    price = models.CharField(max_length=32)

（4）配置文件中配置自动生成文档

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

    	}

（5）文档访问地址

http://127.0.0.1:8000/docs

4.接口文档详细内容

-接口描述
    -路由地址
    -请求方式
    -请求编码格式
    -请求数据详解(必填，类型)
    -返回格式案例
    -返回数据字段解释
    -错误码

2.JWT介绍和原理

1.Cookie、session、Token的发展史

2.JWT简介

JWT为JSON Web Token，是为了在网络应用环境间传递声明而执行的一种基于JSON的开放标准（(RFC 7519)。

该token被设计为紧凑且安全的，特别适用于分布式站点的单点登录（SSO）场景。

JWT的声明一般被用来在身份提供者和服务提供者间传递被认证的用户身份信息，以便于从资源服务器获取资源，也可以增加一些额外的其它业务逻辑所必须的声明信息，该token也可直接被用于认证，也可被加密。

3.构成

JWT的本质就是token，它主要有三部分组成，分别是头部（header）、荷载（payload）主题部、以及签证（signature）

前两部分都是由base64进行编码（可以反解码），后一部分是不可反解的加密，由前两部分base64的结果加密（hash256）后组成。

各个部分之间由.来分割

如：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

JWT和语言、框架无关

3.JWT的组成部分

header

在header中，一般携带着2部分信息(声明):类型、算法

{
    "type": "JWT",
    "encode_method": "HASH256"
}

payload

荷载一般存放有效信息：

它可以存放三种类型的有效信息：

① 标准中注册的声明

② 公共的声明

③ 私有的声明

标准中注册的声明(建议但不强制使用)：

荷载部位的key	描述
iss	JWT签发者（服务端）
sub	JWT所面向的用户
aud	接收JWT的一方
exp	JWT的过期时间，该时间必须大于签发时间
nbf	再某一时间段之前，该JWT不可用
jti	JWT的唯一身份标识，主要用作一次性token，回避时序攻击

公共的声明：

公共的声明可以添加任何的信息，一般添加用户的相关信息或其他业务需要的必要信息，但不建议添加敏感信息，因为该部分在客户端可解密。

私有的声明：

私有声明是提供者和消费者所共同定义的声明，一般不建议存放敏感信息，因为base64是对称解密的，意味着该部分信息可以归类为明文信息。

自定义payload，JSON格式：

{
    "id": 1024,
    "sub": "1233211234567",
    "name": "Darker",
    "admin": true
}

signature

JWT的第三部分是一个签证信息，这个签证信息由三部分组成

① header (base64后的)

② payload (base64后的)

③ secret

这个部分需要base64加密后的header和base64加密后的payload使用.连接组成的字符串，然后通过header中声明的加密方式进行加盐secret组合加密，然后就构成了JWT的第三部分。

signature = hashlib.sha256()
signature.update(header_payload_result)
salt = 'llnb'
signature.update(salt.encode("utf-8"))    # 加盐
signature_result = signature.hexdigest()    # 获得结果

4.JWT的使用

(1)安装

pip3 install djangorestframework-jwt -i https://pypi.tuna.tsinghua.edu.cn/simple

(2)在django的auth-user表中创建一个用户

(3)在路由中配置

urlpatterns = [
    path('login/', obtain_jwt_token),
    ...
]

(4)用postman向这个地址发送post请求，携带用户名和密码，登录成功则会返回token

(5)obtain_jwt_token本质也是一个视图类，继承了APIView

• 如果前端传入用户名和密码，则开始检验，通过则生成token并返回
• 如果校验失败，则返回错误信息

(6)如果用户携带了token，并配置了【JWT的认证类】，从request.user就能拿到当前登录的用户，如果没有携带，request.user就是匿名用户

(7)前端要发送请求，携带JWT格式如下

• 把token放在请求头中，key为Authorization
• value必须为jwt

{"Authorization":"jwt"}

5.定制返回格式

在 jwt的 utils.py中的jwt_response_payload_handler 函数控制着完成 jwt验证后返回的格式，通过重写该函数，我们可以定制返回的格式

（1）重写jwt_response_payload_handler方法

def jwt_response_payload_handler(token, user=None, request=None):
    # 获取用户的登录时间

    user.last_login = datetime.datetime.today()
    user.save()

    return {
        "code": 100,
        "msg": "token认证通过，登录成功",
        "token": token,
        "username": user.username,
        "time": user.last_login,

    }

（2）settings.py中配置

JWT_AUTH = {
    	'JWT_RESPONSE_PAYLOAD_HANDLER': 'app01.utils.jwt_response_payload_handler',  
	}

（3）实用postman测试

6.JWT的认证类

JWT的认证还需要配合权限类来使用

(1)导入认证类与权限类

from rest_framework_jwt.authentication import JSONWebTokenAuthentication
from rest_framework.permissions import IsAuthenticated

(2)在视图类上加一个认证类，一个权限类

"认证类"
authentication_classes = [JSONWebTokenAuthentication]
"权限类"
permission_classes = [IsAuthenticated]