08-接口文档和JWT

人のエゴで造られた虚にだけはなりたくはなくて / 2024-04-19 / 原文

接口文档

楔子

接口文档对于协调前后端开发非常重要，可以避免因为开发习惯不同而导致的意外情况。在项目中，如果前后端开发各自为战，可能会出现不一致的情况。因此，接口文档可以约束双方，确保他们按照统一的规范进行开发，从而提高协同开发的效率和一致性。

规范

接口文档一般包括以下内容：

接口描述: 对每个接口进行描述，包括其功能、输入参数、输出格式和预期行为。
请求方法: 每个接口支持的请求方法，例如 GET、POST、PUT、DELETE 等。
请求参数: 每个接口所需的请求参数，包括参数名、类型、是否必需等信息。
响应格式: 每个接口的响应格式，包括响应数据的结构、类型等信息。
错误处理: 定义了接口可能返回的错误状态码和对应的错误信息，以及客户端应该如何处理这些错误。
示例: 可能包括一些请求和响应的示例，以便开发人员更好地理解接口的使用方式。
安全要求: 如果接口需要进行身份验证或授权，接口文档应包括相应的安全要求和机制。
版本控制: 如果接口存在多个版本，接口文档应该明确标明每个版本的区别和兼容性信息。

接口文档展现形式

word形式

markdown形式

json和yaml

公司自研

开源的接口文档平台

比如Yapi 百度开源的

通过项目，自动生成接口文档平台

coreapi

drf-yasg

接口文档命名，建议包含版本字样，比如：书籍请求接口-v1.md

一个简单的接口文档实例

# 1. 用户相关
## 1.1 登录接口
	# 请求地址
	# 请求参数
	# 编码格式
	# 响应字段详解
## 1.2 注册接口
	# 请求地址
	# 请求参数
	# 编码格式
	# 响应字段详解

	# ...

自动生成接口文档 coreapi （了解）

安装

pip install coreapi

使用

# 路由层
from rest_framework.documentation import include_docs_urls

urlpatterns = [
    path("docs/", include_docs_urls(title="书籍查询接口文档"))
]

# 视图层
from rest_framework.viewsets import ModelViewSet
from .serializer import BookSerializer
from .models import Book

class BookViewSet(ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

如果遇到报错

#AttributeError: 'AutoSchema' object has no attribute 'get_link'
REST_FRAMEWORK = {
 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
    # 新版drf schema_class默认用的是rest_framework.schemas.openapi.AutoSchema
}

启动项目：http://127.0.0.1:8000/app01/docs/

说明

模型层种的 help_text 控制描述文本，即上图种的出版社

因为序列化层和模型层的字段基本一样，所以序列化层设置一样的，二选一即可。

必填和不必填，取决于序列化类中的required参数默认为True，不必填写成False即可。

方法下的3引号注释，会生成介绍，response的文本会返回结果

def list(self, request):
    """
        查询全部书籍的接口
        """
    return Response("接口描述")

jwt

详细介绍：https://www.ruanyifeng.com/blog/2018/07/json_web_token-tutorial.html

JSON Web Token（缩写 JWT）是目前最流行的跨域认证解决方案。
使用jwt 必须使用django自带的user表。

并不限制语言，所有的web框架都可以采用这种认证方式。

三段式，用 . 去分割每一段使用base64编码（base64不是加密方案，只是编码方案）

头一般放：公司信息，加密方式，是jwt，一般都是固定的

header

荷载一般放：登录用户的信息：用户名，用户id，过期时间，签发时间，是否是超级用户。。

payload

签名 signature 二进制数据校验阶段主要是第三段。

签发阶段：通过头和荷载使用某种加密方式[HS256,md5,sha1等]加密得到。

校验阶段：拿到token，取出第一和第二部分，通过同样的加密方式获得新前面，用新的签名对比第三段（老签名）比较，如果一样，说明数据没有被修改，信任，正常处理。如果不一样，说明数据被篡改或者是模拟生成的，不能信任，返回错误。

注：这个生成的token 浏览器可以截获，不修改，然后模拟发送请求，不能避免。

jwt实现了，数据不在后端，但是比cookie更安全。

access token默认只有5分钟有效。

浏览器大部分可以看到荷载，但是看不到第一阶段的数据（盐）
django中的盐默认在setting中
SECRET_KEY = "django-insecure-b_$m3)zmrq5sy&j_4l&qwylk%&-bkn5k1!-a^!j_#*-!gw37!1"

-是一种前后端登陆认证的方案，区别于之前的 cookie，session
-它有 签发阶段--》登陆成功后签发
-它有 认证阶段--》需要登陆后才能访问的接口，通过认证后，才能继续操作

三段式 使用  . 去分割 
这三段分别代表什么？

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

base64编码

用途：

网络中传输

图片传输

jwt使用

如何使用：

编码：

文字或者图片编码成二进制

使用base64.继续编码即可

解码：

使用base64.b64decode(二进制即可）

如果是文本，再转成文本即可。

base64编码一长度一定是4的倍数，如果不是用=号补齐，正常情况下=号最多3为，如果解不出可以尝试加=号，如果已经满足了，后面可以写N个等号。

编码文本

In [2]: import base64

In [3]: name = '小满'

In [4]: base64.b64encode(name.encode("utf-8"))
Out[4]: b'5bCP5ruh'

In [5]: base64.b64decode(b'5bCP5ruh').decode()
Out[5]: '小满'

编码图片

import base64

# 输入图片文件路径
input_path = r"C:\小满\Pictures\best.jpg"

# 输出的 base64 编码后的文本文件路径
output_path = "./结果.txt"

# 将图片文件编码为 base64 并写入到文本文件中
with open(input_path, "rb") as f1, open(output_path, "wb") as f2:
    while data := f1.read():
        # 编码为 base64
        encoded_data = base64.b64encode(data)
        # 将编码后的数据写入文本文件
        f2.write(encoded_data)

# 从 base64 编码的文本文件解码并写入到新的图片文件中
with open(output_path, "rb") as f1, open("./小满.jpg", "wb") as f2:
    while data := f1.read():
        # 解码 base64 数据
        decoded_data = base64.b64decode(data)
        # 将解码后的数据写入新的图片文件
        f2.write(decoded_data)

jwt开发重点

-签发token---》登陆接口
-校验token---》认证类

如何使用

登陆签发：默认使用auth的user表

# 自己写：登录 认证
# 第三方：方便快捷

# python的django框架中使用jwt
	- 安装
    - pip install djangorestframework-simplejwt
    
# 路由层
from rest_framework_simplejwt.views import token_obtain_pair

urlpatterns = [
    path("login/", token_obtain_pair)  # http:127.0.0.1:8000/login/  --> post请求 即可
]

# 视图层
from rest_framework.views import APIView
from rest_framework.mixins import CreateModelMixin


# 测试jwt
class LoginView(APIView, CreateModelMixin):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

必须登录后才能发送post 比如新增一本图书其他的视图（路由按上面的配置即可）

from rest_framework.permissions import IsAuthenticated  # 第一个模块
from rest_framework_simplejwt.authentication import JWTAuthentication  # 第二个模块



# 书籍 测试接口工具
class BookViewSet(ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer
    
     # 必须登录后才能新增
    authentication_classes = [JWTAuthentication] # 第一位
    permission_classes = [IsAuthenticated]  # 第二位