django-apis 0.2.11

Django简易json api接口封装。

django-apis

Django简易json api接口框架。使用pydantic做接口参数验证。

安装

pip install django-apis

配置项

• DJANGO_APIS_OPENAPI_TITLE: Swagger标题。

• DJANGO_APIS_OPENAPI_VERSION: Swagger版本号。

• DJANGO_APIS_OPENAPI_DESCRIPTION: Swagger描述。

• DJANGO_APIS_OPENAPI_LOGIN_URL: Swagger管理界面访问受管理登录保护。在未登录访问时跳转的登录页面地址。

• DJANGO_APIS_SWAGGER_UI_PATH: Swagger管理界面二级路径（不包括django_apis.urls引入部分）。默认值为/docs/。

• DJANGO_APIS_OPENAPI_SERVERS: Swagger服务器列表。

  DJANGO_APIS_OPENAPI_SERVERS = [
      {"url": "http://127.0.0.1:8000", "description": "本地开发环境"},
      {"url": "http://192.168.11.123", "description": "测试环境"},
  ]
  

• DJANGO_APIS_OPENAPI_SECURITY_DEFINITIONS: Swagger认证列表。

  DJANGO_APIS_OPENAPI_SECURITY_DEFINITIONS = {
      "BasicAuth": {
          "type": "http",
          "scheme": "basic",
      },
      "BearerAuth": {
          "type": "http",
          "scheme": "bearer",
      },
      "ApikeyAuth": {
          "type": "apiKey",
          "name": "X-API-Key",
          "in": "header",
      },
      "OpenID": {
          "type": "openIdConnect",
          "openIdConnectUrl": "https://example.com/.well-known/openid-configuration",
      },
      "OAuth2": {
          "type": "oauth2",
          "flows": {
              "authorizationCode": {
                  "authorizationUrl": "https://example.com/oauth/authorize",
                  "tokenUrl": "https://example.com/oauth/token",
                  "scopes": {
                      "read": "Grants read access",
                      "write": "Grants write access",
                      "admin": "Grants access to admin operations",
                  },
              }
          },
      },
  }
  

如何自定义Apiview类型

注意事项

1. 定义自己的base_response_class，并重置自定义的Apiview中的base_response_class属性。
2. 重载Apiview中的make_response和make_error_response方法。

自定义Apiview类型案例

from django.http import JsonResponse
from django_apis.views import Apiview
from django_apis.schemas import ResponseBase
from typing import Any
import pydantic

class ErrorInfo(pydantic.BaseModel):
    code: int = 0
    message: str = "OK"

# 响应体格式定义要与make_response及make_error_response实际响应匹配
class ExampleApiviewResponseBase(ResponseBase):
    success: bool = True
    error: ErrorInfo = ErrorInfo()
    result: Any = None

class ExampleApiview(Apiview):
    base_response_data_field = "result"
    base_response_class = ExampleApiviewResponseBase

    def make_response(self, data):
        return JsonResponse(
            {
                "success": True,
                "error": {
                    "code": 0,
                    "message": "OK",
                },
                "result": data,
            },
            json_dumps_params={
                "ensure_ascii": False,
            },
        )

    # 强制所有响应的http status_code值为200
    def make_error_response(self, code, message, status_code=200):
        return JsonResponse(
            {
                "success": True,
                "error": {
                    "code": code,
                    "message": message,
                },
                "result": None,
            },
            json_dumps_params={
                "ensure_ascii": False,
            },
        )

example_apiview = ExampleApiview()

使用案例

import pydantic
from django_apis.views import apiview
from django_apis.schemas import OptionalUploadedFiles

@apiview()
def ping() -> str:
    return "pong"


class EchoPayload(pydantic.BaseMode):
    msg: str

@apiview(methods="post")
def echo(payload: EchoPayload) -> str:
    return payload.msg

class ApplyForm(pydantic.BaseMode):
    name: str
    start_date: str
    end_date: str
    files: OptionalUploadedFiles

@apiview(methods="post")
def apply(form: ApplyForm) -> bool:
    return True

版本记录

v0.2.0

• 注意：不兼容0.1.x。

v0.2.1

• 使用openapi 3.1.0版本.
• 添加并通过更多关于复合模型的测试用例。

v0.2.2

• 通过DJANGO_APIS_SWAGGER_LOGIN_REQUIRED配置项控制Swagger管理界面是否受登录保护。

v0.2.3

• 使用typing.Union以兼容python3.9。

v0.2.4

• 为接口添加security字段。

v0.2.5

• query字段添加default支持。

v0.2.6

• get_response_schema结果必须为ResponseBase子类，否则均使用make_generic_response_type进行动态生成。

v0.2.8

• 修正：是否为HttpResponseBase实例判断错误的问题。

v0.2.10

• 添加：django_apis.helper.auth模型，提供http_bearer_auth_protect、http_basic_auth_protect、apikey_auth_protect等认证验证方法。
• 添加：视图级的tags定义支持。

v0.2.11

• 修正: swagger中支持query参数可选。