Flask-RESTful Documentation Release 0.3.8

• 语言: 英语
• 格式: .pdf
• 来源: flask-restful.readthedocs.io

摘要

Flask-RESTful is an extension for Flask that simplifies the creation of REST APIs. The documentation covers installation, quickstart examples, request parsing, output fields, extending Flask-RESTful, and intermediate usage. Key features include resourceful routing, request parsing using reqparse, custom fields definition, error handling, and integration with Flask decorators. The API reference provides detailed information on how to use Flask-RESTful in various scenarios.

AI总结

### Flask-RESTful 0.3.8 发行说明总结

#### 1. 安装
- 使用 `pip` 安装：`pip install flask-restful`
- 依赖：Flask 0.10 或更高版本
- 支持 Python 版本：2.7、3.4、3.5、3.6、3.7

#### 2. 快速入门
- 创建一个简单的 REST API：

  from flask import Flask
  from flask_restful import Resource, Api

  app = Flask(__name__)
  api = Api(app)

  class HelloWorld(Resource):
      def get(self):
          return {'hello': 'world'}

  api.add_resource(HelloWorld, '/')
  if __name__ == '__main__':
      app.run(debug=True)

- 使用 `curl` 测试：

  curl http://localhost:5000/

#### 3. 请求解析
- 基于 `reqparse` 的请求解析器类似于 `argparse`，用于统一访问 `flask.request` 对象。
- 注意：`reqparse` 已标记为弃用，建议集成其他库（如 `marshmallow`）进行输入输出处理。

#### 4. 输出字段
- 支持自定义输出格式，例如通过继承 `Raw` 类并重写 `format()` 方法。
- 示例：

  class AllCapsString(fields.Raw):
      def format(self, value):
          return value.upper()

  fields = {
      'name': fields.String,
      'all_caps_name': AllCapsString(attribute='name'),
  }

#### 5. 扩展 Flask-RESTful
- 支持自定义媒体类型和 JSON 表示函数：

  @api.representation('application/json')
  def output_json(data, code, headers=None):
      resp = make_response(json.dumps(data), code)
      resp.headers.extend(headers or {})
      return resp

- 可通过 `RESTFUL_JSON` 配置 JSON 格式化选项。

#### 6. 中间级用法
- **缓存装饰器**：仅应用于特定方法（如 `GET`）。
- **自定义错误处理**：
- 定义错误消息和状态码：

    errors = {
        'UserAlreadyExistsError': {
            'message': 'A user with that username already exists.',
            'status': 409,
        },
        # 其他错误定义
    }

- 传递到 `Api` 构造函数：`api = Api(app, errors=errors)`
- 使用 `got_request_exception` 钩子处理自定义错误日志：

    def log_exception(sender, exception, **extra):
        sender.logger.debug('Got exception during processing: %s', exception)

    got_request_exception.connect(log_exception, app)

#### 7. 其他注意事项
- **测试运行**：文档末尾提供了测试运行的说明。
- **符号索引**：包含模块和类的详细符号列表，供进一步查阅。

### 总结
Flask-RESTful 是一个轻量级的 Flask 扩展，支持快速构建 REST API。通过简洁的语法和灵活的扩展机制，开发者可以轻松实现资源路由、请求解析、输出格式化和错误处理等功能。