指定并验证djangoapi
django-api的Python项目详细描述
django_api允许您在单个代码块中指定和验证Djangoapi。
它使用包装django视图的@apidecorator来实现这一点。这将保持api文档的一致性、本地化和声明性。
from django import forms
from django_api.decorators import api
from django_api.json_helpers import JsonResponse
from django_api.json_helpers import JsonResponseForbidden
@api({
'accepts': {
'x': forms.IntegerField(min_value=0),
'y': forms.IntegerField(max_value=10),
},
'returns': {
200: 'Addition successful',
}
})
def add(request, *args, **kwargs):
# `x` and `y` have been validated, and are integers
# so we can safely perform arithmetic operations on them
return JsonResponse({
'sum': request.GET['x'] + request.GET['y']
})
基于以上示例，以下api响应将自动可用（假设您将/add路由连接到上面的视图：
GET /add
"failed to validate: {'y': [u'This field is required.'], 'x': [u'This field is required.']}"
GET /add?x=10
"failed to validate: {'y': [u'This field is required.']}"
GET /add?x=10&y=100
"failed to validate: {'y': [u'Ensure this value is less than or equal to 10.']}"
GET /add?x=10&y=10
{sum: 20}
依赖关系
无
安装
要在django项目中使用django_api，您的 python安装：
$ pip install django-api
（或者简单地将django_api目录放在$python路径中）
django设置
将django_api添加到项目的settings.py中的INSTALLED_APPS。
示例：
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'django.contrib.admin',
'django_api',
)
用法
使用@apidecorator指定api。@apidecorator接受一个带两个键的字典：accepts和returns。
from django_api.decorators import api
@api({
'accepts': {
},
'returns': {
}
})
def add(request, *args, **kwargs):
接受
通过在accepts字典中列出api接受的查询参数来描述它们。accepts节中的每个条目 将名称映射到Django form field类型。 接收的查询参数将自动转换为指定类型。如果参数不符合规范 查询无法验证（见下文）。 一旦验证，变量将被放置在request字典中，以便在视图中使用。
'accepts': {
'x': forms.IntegerField(min_value=0),
'y': forms.IntegerField(max_value=10, required=False),
'u': User(),
}
由于每个参数都是使用django表单字段指定的，因此可以使用其类构造函数采用的任何参数。示例包括
- required
- initial
- max_length用于CharField
- min_value用于IntegerField
完整的参考资料请see here。
返回
默认情况下，@apidecorator检查返回的响应是否为json类型。
通过在returns字典中列出有效的返回http代码来指定它们。 字典中的每个条目都将一个http响应代码映射到一个有用的消息，解释结果 关于这次行动。此有用消息仅用于文档目的。 如果响应不符合规范，则查询将无法验证（见下文）。
'returns': {
200: 'Addition successful',
403: 'User does not have permission',
404: 'Resource not found',
404: 'User not found',
}
验证
如果验证失败，则向客户端返回HTTP 400 - Bad request。为了安全起见，django_api将仅在settings.DEBUG = True时执行验证。 这确保了生产代码始终不受影响。
测试
使用以下命令运行测试
python manage.py test django_api
高级用法
django模型
@accepts还可以通过对象的id接受django模型。对于模型Model，django希望查询参数为namemodel-id。
'accepts': {
'x': forms.IntegerField(min_value=0),
'y': forms.IntegerField(max_value=10, required=False),
'u': User(),
}
您也可以选择只验证
api接受，或者api的返回值。
示例：
from django import forms
from django_api.decorators import api_accepts
from django_api.json_helpers import JsonResponse
from django_api.json_helpers import JsonResponseForbidden
@api_accepts({
'x': forms.IntegerField(min_value=0),
'y': forms.IntegerField(min_value=0),
})
def add(request, *args, **kwargs):
return JsonResponse({
'sum': request.GET['x'] + request.GET['y']
})
from django import forms
from django_api.decorators import api_returns
from django_api.json_helpers import JsonResponse
from django_api.json_helpers import JsonResponseForbidden
@api_returns({
200: 'Operation successful',
403: 'User does not have permission',
404: 'Resource not found',
404: 'User not found',
})
def add(request, *args, **kwargs):
return JsonResponse({
'sum': request.GET['x'] + request.GET['y']
})
欢迎加入QQ群-->： 979659372
