HTTP API输入/输出管理器
项目描述
hapic概述
hapic是一个与框架无关的库，用于编写专业的REST API。
哲学
hapic是在一个大型面向服务型项目的背景下由algoo开发的。缺乏能够实现Rest API真实自动文档化的工具，使我们决定开发hapic。
目标用途不是用于“快速且脏”的事情，而是用于专业、可维护、长期目标的项目。
REST API层与业务逻辑层之间的关注点分离是hapic的DNA。
hapic只是在您的业务代码之上只是一个HTTP层粘合代码。
使用hapic的直接好处
当您决定基于hapic进行开发时，您将获得直接的好处
可直接使用
- 支持aiohttp、flask、pyramid和bottle
- 与现有库直接兼容
- 轻松地将异常映射到HTTP错误
- 基于marshmallow模式或serpyco数据类的序列化
完整的API文档已准备好
- 您的代码 是 文档
- 生成的Swagger文档
- 将文档嵌入到一行代码中
- 支持Python 3.5、3.6和3.7
专业且可维护的源代码
- 业务逻辑与HTTP内容之间的关注点分离
- 当与aiohttp和serpyco一起使用时非常快速
- 可扩展的框架，用于支持其他Web框架和序列化库
许可证
hapic根据MIT许可证授权。您可以在您的项目中使用它，无论是封闭源代码还是开源。
状态，贡献
hapic的源代码已准备好投入生产。已经识别出一些需要进行重构以实现可维护性，但公共API是稳定的，因此您可以依赖hapic进行开发。
hapic正在积极开发中，基于不同的专业项目。如果您发现错误或想要添加功能，我们将回答您的问题并接受合并请求。
hapic已在Python 3.5、3.6和3.7上自动测试
待办事项引用
代码中的待办事项可以包含一些 #xxx - 这些是 GitHub 问题引用。
安装
为了使用 yaml 模块获得更好的性能，您可以安装以下内容（Debian 指令）
sudo apt-get install libyaml-dev
libyaml-dev 包在安装 hapic 后可以移除。
从源代码
virtualenv -p /usr/bin/python3 venv
source venv/bin/activate
python setup.py develop
为了使用 Marshmallow 架构，安装必要的依赖项
pip install -e ".[marshmallow]"
为了使用 Serpyco 数据类，安装必要的依赖项
pip install -e ".[serpyco]"
拥有完整的开发环境
pip install -e ".[dev"]
从 PyPI
为了使用 Marshmallow 架构，安装必要的依赖项
pip install hapic[marshmallow]
为了使用 Serpyco 数据类，安装必要的依赖项
pip install hapic[serpyco]
试试看
简短的 Flask 示例
from datetime import datetime
import flask
import marshmallow
import hapic
from hapic.ext.flask import FlaskContext
import json
hapic = hapic.Hapic()
app = flask.Flask(__name__)
class UriPathSchema(marshmallow.Schema): # schema describing the URI and allowed values
name = marshmallow.fields.String(required=True)
age = marshmallow.fields.Integer(required=False)
class HelloResponseSchema(marshmallow.Schema): # schema of the API response
name = marshmallow.fields.String(required=True)
now = marshmallow.fields.DateTime(required=False)
greetings = marshmallow.fields.String(required=False)
@app.route('/hello/<name>') # flask route. must always be before hapic decorators
@hapic.with_api_doc() # the first hapic decorator. Register the method for auto-documentation
@hapic.input_path(UriPathSchema()) # validate the URI structure
@hapic.output_body(HelloResponseSchema()) # define output structure
def hello(name='<No name>', hapic_data=None):
return {
'name': name,
'now': datetime.now(),
'dummy': { 'some': 'dummy' } # will be ignored
}
class UriPathSchemaWithAge(marshmallow.Schema): # schema describing the URI and allowed values
name = marshmallow.fields.String(required=True)
age = marshmallow.fields.Integer(required=False)
@app.route('/hello/<name>/age/<age>')
@hapic.with_api_doc()
@hapic.input_path(UriPathSchemaWithAge())
@hapic.output_body(HelloResponseSchema())
def hello2(name='<No name>', age=42, hapic_data=None):
return {
'name': name,
'age': age,
'greetings': 'Hello {name}, it looks like you are {age}'.format(
name=name,
age=age
),
'now': datetime.now(),
'dummy': { 'some': 'dummy' } # will be ignored
}
hapic.set_context(FlaskContext(app))
print(json.dumps(hapic.generate_doc(title='API Doc', description='doc desc.'))) # Generate the documentation
app.run('127.0.0.1', 8080, debug=True)
如何使用它
正常情况
$ curl "http://127.0.0.1:8080/hello/michel"
# {"now": "2017-12-18T12:37:10.751623+00:00", "name": "michel"}
$ curl "http://127.0.0.1:8080/hello/michel/age/17"
# {"name": "damien", "greetings": "Hello damien, it looks like you are 17", "now": "2017-12-18T12:41:58.229679+00:00"}
错误情况（返回 400）
$ curl "http://127.0.0.1:8080/hello/michel/age/mistaken"
# {"details": {"age": ["Not a valid integer."]}, "message": "Validation error of input data"}
完整的用户 API
在 example/usermanagement 目录中，您可以找到一个允许管理用户的完整 API 示例。
功能包括
- 获取所有用户的列表
- 获取指定用户的详细信息
- 创建一个用户
- 删除一个用户
为了测试它
安装所需的依赖项
pip install bottle flask pyramid`
运行您想要测试的实例（以下三条命令中的一条）
python example/usermanagement/serve_bottle.py
python example/usermanagement/serve_flask.py
python example/usermanagement/serve_pyramid.py
显示的功能
- 自动生成文档
- 管理 URI 路径中的参数
- 管理输入架构
- 管理输出架构
- 管理错误情况（404、500 等）
- 优雅的异常处理
- 自动字典/对象序列化
关闭
hapic-0.98.tar.gz 的散列值
| 算法 | 散列摘要 | |
|---|---|---|
| SHA256 | d9e05960dab04205ec2b6e3a252d0a6224313aa00e1ac28c504ab5a204b82655 |
|
| MD5 | 61666c817332bf93a0b892e6d7454f5e |
|
| BLAKE2b-256 | 05d2844e43e29f68d6bc35c1ca2b119db6b8f10ccf81b9ed08c389a9086ccfea |
