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

这些详情尚未由PyPI验证

项目链接

主页

项目描述

Flasgger

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

flasgger

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

Flasgger还内置了SwaggerUI，因此您可以通过https://:5000/apidocs访问并可视化、交互您的API资源。

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

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

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

Flasgger还支持Marshmallow APISpec作为规范的基本模板，如果您正在使用Marshmallow的APISPec，请参阅apispec示例。

主要贡献者
示例和演示应用
- Docker
安装
入门
使用相同的数据验证您的API POST正文。
- 自定义验证
- 验证错误处理
获取定义的模式作为Python字典
HTML清洗器
Swagger UI和模板
支持OpenAPI 3.0
- 外部加载Swagger UI和jQuery JS/CSS
使用默认数据初始化Flasgger
- 在运行时获取默认数据
- 位于反向代理之后
自定义默认配置
- 提取定义
- 兼容Python2

由gh-md-toc创建

主要贡献者

示例和演示应用

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

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

Docker

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

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

然后通过https://:5000访问Flasgger演示应用程序。

安装

在您的virtualenv下执行以下操作：

确保您有最新的setuptools

pip install -U setuptools

然后

pip install flasgger

或（开发版本）

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

注意：如果您想使用Marshmallow Schemas，您还需要运行pip install marshmallow apispec

如何运行测试

（您可以在.travis.yml的before_install部分看到该命令）

在您的virtualenv中

pip install -r requirements.txt
pip install -r requirements-dev.txt
make test

入门

使用文档字符串作为规范

创建一个名为，例如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': ['cyan', '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

然后转到：https://: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 Schemas

第一步：pip install marshmallow apispec

用法#1：SwaggerView

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': ['cyan', '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)

用法#2：来自flasgger的自定义Schema

Body - 支持marshmallow中的所有字段
Query - 支持marshmallow中的简单字段（Int，String等）
Path - 只支持int和str

from flask import Flask, abort
from flasgger import Swagger, Schema, fields
from marshmallow.validate import Length, OneOf

app = Flask(__name__)
Swagger(app)

swag = {"swag": True,
        "tags": ["demo"],
        "responses": {200: {"description": "Success request"},
                      400: {"description": "Validation error"}}}


class Body(Schema):
    color = fields.List(fields.String(), required=True, validate=Length(max=5), example=["white", "blue", "red"])

    def swag_validation_function(self, data, main_def):
        self.load(data)

    def swag_validation_error_handler(self, err, data, main_def):
        abort(400, err)


class Query(Schema):
    color = fields.String(required=True, validate=OneOf(["white", "blue", "red"]))

    def swag_validation_function(self, data, main_def):
        self.load(data)

    def swag_validation_error_handler(self, err, data, main_def):
        abort(400, err)

    swag_in = "query"


@app.route("/color/<id>/<name>", methods=["POST"], **swag)
def index(body: Body, query: Query, id: int, name: str):
    return {"body": body, "query": query, "id": id, "name": name}

if __name__ == "__main__":
    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})

您也可以通过多次注册url_rule在MethodView或SwaggerView的多个方法中实现相同的效果。请参阅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函数将强制使用默认验证函数。

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函数将强制使用默认验证函数。

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将尝试通过将每个\n替换为<br>来净化YAML定义中的内容，但您可以设置其他类型的净化器。

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解析器可用，如果您想能够在规范描述中渲染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版本开始，您可以为加载Flasgger默认模板中包含的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, etc..，也可能需要访问数据库。

位于反向代理之后

有时您可能需要在反向代理（例如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)

自定义默认配置

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

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)

提取定义

当在spec中找到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': ['cyan', '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添加到您的模式中。

兼容Python2

版本0.9.5.*将是最后一个支持Python2的版本。请将讨论引导至#399。

项目详情

这些详情尚未由PyPI验证

项目链接

主页

发布历史发布通知 | RSS源

本版本

0.9.7

2022年10月21日

0.9.5

2022年10月21日

下载文件

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

源代码发行版

flasgger-tschaume-0.9.7.tar.gz (4.2 MB 查看哈希值)

上传时间 2022年10月21日 源代码

构建发行版

flasgger_tschaume-0.9.7-py2.py3-none-any.whl (3.9 MB 查看哈希值)

上传时间 2022年10月21日 Python 2 Python 3

flasgger-tschaume-0.9.7.tar.gz的哈希值

flasgger-tschaume-0.9.7.tar.gz的哈希值
算法	哈希摘要
SHA256	`139bd4686387e69019af2a86c0eacbd00bf30df0c7470ea55120646cab2ae446`
MD5	`e3bd650498988569403e341a5aeca36c`
BLAKE2b-256	`ad9a94f78b4865f30402dd56f343d0d7487b2d6fce3137a3579a18aa49981bd8`

flasgger_tschaume-0.9.7-py2.py3-none-any.whl的哈希值

flasgger_tschaume-0.9.7-py2.py3-none-any.whl的哈希值
算法	哈希摘要
SHA256	`ee0c55f76c5884704649d139f042050af5d6f1d5a60cae167e3123735720302c`
MD5	`ce2d37c0ae8cf096b0e2e3a34478a1b3`
BLAKE2b-256	`97a7f6b8b0d622449b0e63869d64c3ad19d67b5e86e1bad60e3c34cbb9dc2ca6`

flasgger-tschaume 0.9.7

导航

验证详情

维护者

未经验证的详情

项目链接

元数据

分类器

项目描述

Flasgger

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

目录

主要贡献者

示例和演示应用

Docker

安装

如何运行测试

入门

使用文档字符串作为规范

使用外部YAML文件

使用字典作为原始规范

使用Marshmallow Schemas

使用Flask RESTful资源

自动解析外部YAML文档和MethodView

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

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

自定义验证

验证错误处理

获取定义的模式作为Python字典

HTML清洗器

Swagger UI和模板

支持OpenAPI 3.0

外部加载Swagger UI和jQuery JS/CSS

使用默认数据初始化Flasgger

在运行时获取默认数据

位于反向代理之后

自定义默认配置

提取定义

兼容Python2

项目详情

验证详情

维护者

未经验证的详情

项目链接

元数据

分类器

发布历史 发布通知 | RSS源

下载文件

源代码发行版

构建发行版

使用`Flask RESTful`资源

自动解析外部YAML文档和`MethodView`

发布历史发布通知 | RSS源