从您的Flask项目中提取swagger规范

导航

验证详情

这些详情已由PyPI验证
维护者
Avatar for nicobatty from gravatar.com nicobatty

未验证详情

这些详情尚未由PyPI验证
项目链接
元数据

项目描述

Flasgger

为您的Flask API提供简单的Swagger UI

Build Status Code Health Coverage Status PyPI Donate with Paypal

flasgger

Flasgger是一个Flask扩展，用于从您的API中所有注册的Flask视图中提取OpenAPI规范。

Flasgger还内置了SwaggerUI，因此您可以访问http://localhost:5000/apidocs并可视化以及与API资源交互。

Flasgger还提供了对传入数据的验证，使用相同的规范，它可以验证接收到的POST、PUT、PATCH数据是否与使用YAML、Python字典或Marshmallow Schemas定义的架构有效。

Flasgger可以与简单函数视图或MethodViews一起使用，使用文档字符串作为规范，或使用@swag_from装饰器从YAML或字典中获取规范，同时还提供了可以使用Marshmallow Schemas作为规范的SwaggerView。

Flasgger与Flask-RESTful兼容，因此您可以使用Resources和swag规范一起使用，请查看restful示例。

Flasgger也支持使用Marshmallow APISpec作为规范的基础模板，如果您使用APISPec从Marshmallow，请查看apispec示例。

主要贡献者

示例和演示应用

有一些示例应用程序，您还可以在Flasgger演示应用中尝试示例。

注意：所有示例应用也是测试用例，并在Travis CI中自动运行以确保质量和覆盖率。

Docker

示例和演示应用也可以构建并作为Docker镜像/容器运行。

docker build -t flasgger .
docker run -it --rm -p 5000:5000 --name flasgger flasgger

然后访问Flasgger演示应用程序：http://localhost:5000。

安装

在你的virtualenv下执行

确保你有最新的setuptools

pip install -U setuptools

然后

pip install flasgger

或者（开发版本）

pip install https://github.com/rochacbruno/flasgger/tarball/master

注意：如果你想使用Marshmallow模式，还需要运行pip install marshmallow apispec

入门

使用docstrings作为规范

创建一个名为例如colors.py的文件

from flask import Flask, jsonify
from flasgger import Swagger

app = Flask(__name__)
swagger = Swagger(app)

@app.route('/colors/<palette>/')
def colors(palette):
    """Example endpoint returning a list of colors by palette
    This is using docstrings for specifications.
    ---
    parameters:
      - name: palette
        in: path
        type: string
        enum: ['all', 'rgb', 'cmyk']
        required: true
        default: all
    definitions:
      Palette:
        type: object
        properties:
          palette_name:
            type: array
            items:
              $ref: '#/definitions/Color'
      Color:
        type: string
    responses:
      200:
        description: A list of colors (may be filtered by palette)
        schema:
          $ref: '#/definitions/Palette'
        examples:
          rgb: ['red', 'green', 'blue']
    """
    all_colors = {
        'cmyk': ['cian', 'magenta', 'yellow', 'black'],
        'rgb': ['red', 'green', 'blue']
    }
    if palette == 'all':
        result = all_colors
    else:
        result = {palette: all_colors.get(palette)}

    return jsonify(result)

app.run(debug=True)

现在运行

python colors.py

然后访问：http://localhost:5000/apidocs/

你应该会得到

colors

使用外部YAML文件

保存一个新的文件colors.yml

Example endpoint returning a list of colors by palette
In this example the specification is taken from external YAML file
---
parameters:
  - name: palette
    in: path
    type: string
    enum: ['all', 'rgb', 'cmyk']
    required: true
    default: all
definitions:
  Palette:
    type: object
    properties:
      palette_name:
        type: array
        items:
          $ref: '#/definitions/Color'
  Color:
    type: string
responses:
  200:
    description: A list of colors (may be filtered by palette)
    schema:
      $ref: '#/definitions/Palette'
    examples:
      rgb: ['red', 'green', 'blue']

让我们使用相同的示例，只更改视图函数。

from flasgger import swag_from

@app.route('/colors/<palette>/')
@swag_from('colors.yml')
def colors(palette):
    ...

如果你不想使用装饰器，可以使用file:快捷方式。

@app.route('/colors/<palette>/')
def colors(palette):
    """
    file: colors.yml
    """
    ...

使用字典作为原始规范

创建一个Python字典，例如

specs_dict = {
  "parameters": [
    {
      "name": "palette",
      "in": "path",
      "type": "string",
      "enum": [
        "all",
        "rgb",
        "cmyk"
      ],
      "required": "true",
      "default": "all"
    }
  ],
  "definitions": {
    "Palette": {
      "type": "object",
      "properties": {
        "palette_name": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Color"
          }
        }
      }
    },
    "Color": {
      "type": "string"
    }
  },
  "responses": {
    "200": {
      "description": "A list of colors (may be filtered by palette)",
      "schema": {
        "$ref": "#/definitions/Palette"
      },
      "examples": {
        "rgb": [
          "red",
          "green",
          "blue"
        ]
      }
    }
  }
}

现在用相同的函数替换YAML文件。

@app.route('/colors/<palette>/')
@swag_from(specs_dict)
def colors(palette):
    """Example endpoint returning a list of colors by palette
    In this example the specification is taken from specs_dict
    """
    ...

使用Marshmallow模式

首先：pip install marshmallow apispec

from flask import Flask, jsonify
from flasgger import Swagger, SwaggerView, Schema, fields


class Color(Schema):
    name = fields.Str()

class Palette(Schema):
    pallete_name = fields.Str()
    colors = fields.Nested(Color, many=True)

class PaletteView(SwaggerView):
    parameters = [
        {
            "name": "palette",
            "in": "path",
            "type": "string",
            "enum": ["all", "rgb", "cmyk"],
            "required": True,
            "default": "all"
        }
    ]
    responses = {
        200: {
            "description": "A list of colors (may be filtered by palette)",
            "schema": Palette
        }
    }

    def get(self, palette):
        """
        Colors API using schema
        This example is using marshmallow schemas
        """
        all_colors = {
            'cmyk': ['cian', 'magenta', 'yellow', 'black'],
            'rgb': ['red', 'green', 'blue']
        }
        if palette == 'all':
            result = all_colors
        else:
            result = {palette: all_colors.get(palette)}
        return jsonify(result)

app = Flask(__name__)
swagger = Swagger(app)

app.add_url_rule(
    '/colors/<palette>',
    view_func=PaletteView.as_view('colors'),
    methods=['GET']
)

app.run(debug=True)

注意：查看examples/validation.py以获取更完整的示例。

注意：在路径规则中捕获参数时，始终使用显式类型，不好的：/api/<username>好的：/api/<string:username>

使用Flask RESTful资源

Flasgger与Flask-RESTful兼容，你只需要安装pip install flask-restful然后

from flask import Flask
from flasgger import Swagger
from flask_restful import Api, Resource

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

class Username(Resource):
    def get(self, username):
       """
       This examples uses FlaskRESTful Resource
       It works also with swag_from, schemas and spec_dict
       ---
       parameters:
         - in: path
           name: username
           type: string
           required: true
       responses:
         200:
           description: A single user item
           schema:
             id: User
             properties:
               username:
                 type: string
                 description: The name of the user
                 default: Steven Wilson
        """
        return {'username': username}, 200


api.add_resource(Username, '/username/<username>')

app.run(debug=True)

自动解析外部YAML文档和MethodView

Flasgger可以配置为自动解析外部YAML API文档。在app.config['SWAGGER']中设置doc_dir，Swagger将根据端点名称和方法名称在doc_dir中查找YAML文件来加载API文档。例如，'doc_dir': './examples/docs/'和文件./examples/docs/items/get.yml将为ItemsView方法的get提供Swagger文档。

此外，当使用如上所述的Flask RESTful时，通过在构建Swagger时传递parse=True，Flasgger将使用flask_restful.reqparse.RequestParser，定位所有MethodView，解析和验证后的数据将存储在flask.request.parsed_data中。

处理单个函数的多个http方法和路由

你可以通过端点或方法来分离规范

from flasgger.utils import swag_from

@app.route('/api/<string:username>', endpoint='with_user_name', methods=['PUT', 'GET'])
@app.route('/api/', endpoint='without_user_name')
@swag_from('path/to/external_file.yml', endpoint='with_user_name')
@swag_from('path/to/external_file_no_user_get.yml', endpoint='without_user_name', methods=['GET'])
@swag_from('path/to/external_file_no_user_put.yml', endpoint='without_user_name', methods=['PUT'])
def fromfile_decorated(username=None):
    if not username:
        return "No user!"
    return jsonify({'username': username})

同样，在MethodView或SwaggerView中使用多个方法也可以实现，通过多次注册url_rule。查看examples/example_app

使用相同的数据验证你的API POST正文。

将swag_from的validation参数设置为True将自动验证传入的数据

from flasgger import swag_from

@swag_from('defs.yml', validation=True)
def post():
    # if not validate returns ValidationError response with status 400
    # also returns the validation message.

使用swagger.validate注释也是可能的

from flasgger import Swagger

swagger = Swagger(app)

@swagger.validate('UserSchema')
def post():
    '''
    file: defs.yml
    '''
    # if not validate returns ValidationError response with status 400
    # also returns the validation message.

但是，你可以手动调用validate

from flasgger import swag_from, validate

@swag_from('defs.yml')
def post():
    validate(request.json, 'UserSchema', 'defs.yml')
    # if not validate returns ValidationError response with status 400
    # also returns the validation message.

在SwaggerView中定义validation=True也是可能的，并使用specs_dict进行验证。

有关更多信息，请查看examples/validation.py

所有验证选项都可以在https://json-schema.fullstack.org.cn/latest/json-schema-validation.html找到

自定义验证

默认情况下，Flasgger将使用python-jsonschema执行验证。

只要它们符合要求，就支持自定义验证函数

  • 接受两个，并且只有两个位置参数
    • 要验证的数据作为第一个参数；
    • 以及作为第二个参数的验证模式
  • 当验证失败时抛出任何类型的异常。

任何返回值都被丢弃。

将函数提供给Swagger实例将使其成为默认值

from flasgger import Swagger

swagger = Swagger(app, validation_function=my_validation_function)

将函数作为 swag_from 或 swagger.validate 注解的参数或直接传递给 validate 函数，将强制使用该函数而不是 Swagger 的默认验证函数。

from flasgger import swag_from

@swag_from('spec.yml', validation=True, validation_function=my_function)
...

from flasgger import Swagger

swagger = Swagger(app)

@swagger.validate('Pet', validation_function=my_function)
...

from flasgger import validate

...

    validate(
        request.json, 'Pet', 'defs.yml', validation_function=my_function)

验证错误处理

默认情况下，Flasgger 将通过返回带有错误消息的 400 BAD REQUEST 响应来处理验证错误。

可以提供一个自定义的验证错误处理函数来替代默认行为，只要它满足要求。

  • 该函数需要三个，且仅三个位置参数。
    • 第一个参数是引发的错误；
    • 第二个参数是未通过验证的数据；
    • 第三个参数是用于验证的架构。

将函数提供给Swagger实例将使其成为默认值

from flasgger import Swagger

swagger = Swagger(app, validation_error_handler=my_handler)

将函数作为 swag_from 或 swagger.validate 注解的参数或直接传递给 validate 函数，将强制使用该函数而不是 Swagger 的默认验证函数。

from flasgger import swag_from

@swag_from(
    'spec.yml', validation=True, validation_error_handler=my_handler)
...

from flasgger import Swagger

swagger = Swagger(app)

@swagger.validate('Pet', validation_error_handler=my_handler)
...

from flasgger import validate

...

    validate(
        request.json, 'Pet', 'defs.yml',
        validation_error_handler=my_handler)

有关使用自定义验证错误处理函数的示例，请参阅 example validation_error_handler.py

以 Python 字典获取定义的架构

您可能希望使用在 Swagger 规范中定义的架构作为字典，而不复制规范。为此，可以使用 get_schema 方法。

from flask import Flask, jsonify
from flasgger import Swagger, swag_from

app = Flask(__name__)
swagger = Swagger(app)

@swagger.validate('Product')
def post():
    """
    post endpoint
    ---
    tags:
      - products
    parameters:
      - name: body
        in: body
        required: true
        schema:
          id: Product
          required:
            - name
          properties:
            name:
              type: string
              description: The product's name.
              default: "Guarana"
    responses:
      200:
        description: The product inserted in the database
        schema:
          $ref: '#/definitions/Product'
    """
    rv = db.insert(request.json)
    return jsonify(rv)

...

product_schema = swagger.get_schema('product')

此方法返回一个字典，其中包含 Flasgger 架构 ID、所有定义的参数以及所需参数列表。

HTML 清洗器

默认情况下，Flasgger 将尝试清洗 YAML 定义中的内容，将每个 \n 替换为 <br>，但您可以通过设置另一个清洗器来更改此行为。

from flasgger import Swagger, NO_SANITIZER

app =Flask()
swagger = Swagger(app, sanitizer=NO_SANITIZER)

您可以编写自己的清洗器。

swagger = Swagger(app, sanitizer=lambda text: do_anything_with(text))

如果您想在规范描述中渲染 Markdown，则可以使用 MK_SANITIZER。

Swagger UI 和模板

您可以在应用程序中覆盖 templates/flasgger/index.html，该模板将成为 SwaggerUI 的 index.html。使用 flasgger/ui2/templates/index.html 作为定制的基。

Flasgger 支持 Swagger UI 版本 2 和 3，版本 3 仍在实验中，但您可以通过设置 app.config['SWAGGER']['uiversion'] 来尝试。

app = Flask(__name__)
app.config['SWAGGER'] = {
    'title': 'My API',
    'uiversion': 3
}
swagger = Swagger(app)

OpenAPI 3.0 支持

实验性地支持 OpenAPI 3.0，当使用 SwaggerUI 3 时应正常工作。要使用 OpenAPI 3.0，将 app.config['SWAGGER']['openapi'] 设置为当前 SwaggerUI 3 支持的版本，例如 '3.0.2'。

有关使用 callbacks 和 requestBody 的示例，请参阅 callbacks 示例。

外部加载 Swagger UI 和 jQuery JS/CSS

从 Flasgger 0.9.2 版本开始，您可以为加载 Swagger 和 jQuery 库的 JavaScript 和 CSS 指定外部 URL 位置。如果省略以下配置属性，Flasgger 将提供它包含的静态版本 - 这些版本可能比当前 Swagger UI v2 或 v3 发布的版本旧。

以下示例从 unpkg.com 加载 Swagger UI 和 jQuery 版本。

swagger_config = Swagger.DEFAULT_CONFIG
swagger_config['swagger_ui_bundle_js'] = '//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js'
swagger_config['swagger_ui_standalone_preset_js'] = '//unpkg.com/swagger-ui-dist@3/swagger-ui-standalone-preset.js'
swagger_config['jquery_js'] = '//unpkg.com/jquery@2.2.4/dist/jquery.min.js'
swagger_config['swagger_ui_css'] = '//unpkg.com/swagger-ui-dist@3/swagger-ui.css'
Swagger(app, config=swagger_config)

使用默认数据初始化 Flasgger

您可以使用模板提供任何默认数据来开始您的 Swagger 规范。

template = {
  "swagger": "2.0",
  "info": {
    "title": "My API",
    "description": "API for my data",
    "contact": {
      "responsibleOrganization": "ME",
      "responsibleDeveloper": "Me",
      "email": "me@me.com",
      "url": "www.me.com",
    },
    "termsOfService": "http://me.com/terms",
    "version": "0.0.1"
  },
  "host": "mysite.com",  # overrides localhost:500
  "basePath": "/api",  # base bash for blueprint registration
  "schemes": [
    "http",
    "https"
  ],
  "operationId": "getmyData"
}

swagger = Swagger(app, template=template)

然后模板是默认数据，除非某些视图更改它。您还可以提供所有规范作为模板，并且没有视图。或者在外部应用程序中提供视图。

在运行时获取默认数据

有时您需要根据动态值在运行时获取某些数据，例如：您想检查 request.is_secure 以决定 schemes 将是 https。您可以通过使用 LazyString 来实现这一点。

from flask import Flask
from flasgger import, Swagger, LazyString, LazyJSONEncoder

app = Flask(__init__)

# Set the custom Encoder (Inherit it if you need to customize)
app.json_encoder = LazyJSONEncoder


template = dict(
    info={
        'title': LazyString(lambda: 'Lazy Title'),
        'version': LazyString(lambda: '99.9.9'),
        'description': LazyString(lambda: 'Hello Lazy World'),
        'termsOfService': LazyString(lambda: '/there_is_no_tos')
    },
    host=LazyString(lambda: request.host),
    schemes=[LazyString(lambda: 'https' if request.is_secure else 'http')],
    foo=LazyString(lambda: "Bar")
)
Swagger(app, template=template)

LazyString 值将在 jsonify 在运行时编码值时进行评估，因此您可以访问 Flask 的 request, session, g, 等.，并且可能还需要访问数据库。

位于反向代理后面

有时您在反向代理（例如 NGINX）后面提供 Swagger 文档。当遵循 Flask 指导 时，swagger 文档将正确加载，但“尝试它”按钮指向错误的位置。这可以通过以下代码修复

from flask import Flask, request
from flasgger import Swagger, LazyString, LazyJSONEncoder

app = Flask(__name__)
app.json_encoder = LazyJSONEncoder

template = dict(swaggerUiPrefix=LazyString(lambda : request.environ.get('HTTP_X_SCRIPT_NAME', '')))
swagger = Swagger(app, template=template)

自定义默认配置

可以提供自定义配置，例如不同的规范路由或禁用 Swagger UI，并将其提供给 Flasgger。

swagger_config = {
    "headers": [
    ],
    "specs": [
        {
            "endpoint": 'apispec_1',
            "route": '/apispec_1.json',
            "rule_filter": lambda rule: True,  # all in
            "model_filter": lambda tag: True,  # all in
        }
    ],
    "static_url_path": "/flasgger_static",
    # "static_folder": "static",  # must be set by user
    "swagger_ui": True,
    "specs_route": "/apidocs/"
}

swagger = Swagger(app, config=swagger_config)

提取定义

当在规范或示例中找到 id 时，可以提取定义。

from flask import Flask, jsonify
from flasgger import Swagger

app = Flask(__name__)
swagger = Swagger(app)

@app.route('/colors/<palette>/')
def colors(palette):
    """Example endpoint returning a list of colors by palette
    ---
    parameters:
      - name: palette
        in: path
        type: string
        enum: ['all', 'rgb', 'cmyk']
        required: true
        default: all
    responses:
      200:
        description: A list of colors (may be filtered by palette)
        schema:
          id: Palette
          type: object
          properties:
            palette_name:
              type: array
              items:
                schema:
                  id: Color
                  type: string
        examples:
          rgb: ['red', 'green', 'blue']
    """
    all_colors = {
        'cmyk': ['cian', 'magenta', 'yellow', 'black'],
        'rgb': ['red', 'green', 'blue']
    }
    if palette == 'all':
        result = all_colors
    else:
        result = {palette: all_colors.get(palette)}

    return jsonify(result)

app.run(debug=True)

在此示例中，您无需传递 definitions，但需要将 id 添加到您的模式中。

项目详情

验证详情

这些详情已由PyPI验证
维护者
Avatar for nicobatty from gravatar.com nicobatty

未验证详情

这些详情尚未由PyPI验证
项目链接
元数据

发布历史 发布通知 | RSS 源

本版本

0.9.4

0.9.3

下载文件

下载您平台上的文件。如果您不确定选择哪个，请了解更多关于 安装包 的信息。

源分布

nicobatty-flasgger-0.9.4.tar.gz (3.7 MB 查看哈希)

上传时间 源

构建分布

nicobatty_flasgger-0.9.4-py2.py3-none-any.whl (3.7 MB 查看哈希)

上传时间 Python 2 Python 3

由以下支持