flasgger：Flask API的简单OpenAPI规范和Swagger UI

# Flasgger ## Easy Swagger UI for your Flask API [](https://travis-ci.com/flasgger/flasgger) [](https://landscape.io/github/rochacbruno/flasgger/master) [](https://coveralls.io/github/rochacbruno/flasgger?branch=master) [](https://pypi.python.org/pypi/flasgger) <a target="_blank" href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&amp;business=rochacbruno%40gmail%2ecom&amp;lc=BR&amp;item_name=Flasgger&amp;no_note=0&amp;currency_code=USD&amp;bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHostedGuest"><img alt='Donate with Paypal' src='http://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif' /></a>  Flasgger is a Flask extension to **extract [OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object)** from all Flask views registered in your API. Flasgger also comes with **[SwaggerUI](http://swagger.io/swagger-ui/) embedded** so you can access [http://localhost:5000/apidocs](localhost:5000/apidocs) and visualize and interact with your API resources. Flasgger also **provides validation** of the incoming data, using the same specification it can validates if the data received as as a POST, PUT, PATCH is valid against the schema defined using **YAML**, **Python dictionaries** or **Marshmallow Schemas**. Flasgger can work with simple function views or MethodViews using docstring as specification, or using `@swag_from` decorator to get specification from **YAML** or **dict** and also provides **SwaggerView** which can use **Marshmallow Schemas** as specification. Flasgger is compatible with `Flask-RESTful` so you can use `Resources` and `swag` specifications together, take a look at [restful example.](examples/restful.py) Flasgger also supports `Marshmallow APISpec` as base template for specification, if you are using APISPec from Marshmallow take a look at [apispec example.](examples/apispec_example.py) Table of Contents ================= * [Top Contributors](#top-contributors) * [Examples and demo app](#examples-and-demo-app) * [Docker](#docker) * [Installation](#installation) * [Getting started](#getting-started) * [Using docstrings as specification](#using-docstrings-as-specification) * [Using external YAML files](#using-external-yaml-files) * [Using dictionaries as raw specs](#using-dictionaries-as-raw-specs) * [Using Marshmallow Schemas](#using-marshmallow-schemas) * [Using <strong>Flask RESTful</strong> Resources](#using-flask-restful-resources) * [Auto-parsing external YAML docs and MethodViews](#auto-parsing-external-yaml-docs-and-methodviews) * [Handling multiple http methods and routes for a single function](#handling-multiple-http-methods-and-routes-for-a-single-function) * [Use the same data to validate your API POST body.](#use-the-same-data-to-validate-your-api-post-body) * [Custom validation](#custom-validation) * [Validation Error handling](#validation-error-handling) * [Get defined schemas as python dictionaries](#get-defined-schemas-as-python-dictionaries) * [HTML sanitizer](#html-sanitizer) * [Swagger UI and templates](#swagger-ui-and-templates) * [OpenAPI 3.0 Support](#openapi-30-support) * [Externally loading Swagger UI and jQuery JS/CSS](#externally-loading-swagger-ui-and-jquery-jscss) * [Initializing Flasgger with default data.](#initializing-flasgger-with-default-data) * [Getting default data at runtime](#getting-default-data-at-runtime) * [Behind a reverse proxy](#behind-a-reverse-proxy) * [Customize default configurations](#customize-default-configurations) * [Extracting Definitions](#extracting-definitions) * [Python2 Compatibility](#python2-compatibility) Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc) # Top Contributors [](https://sourcerer.io/fame/rochacbruno/rochacbruno/flasgger/links/0)[](https://sourcerer.io/fame/rochacbruno/rochacbruno/flasgger/links/1)[](https://sourcerer.io/fame/rochacbruno/rochacbruno/flasgger/links/2)[](https://sourcerer.io/fame/rochacbruno/rochacbruno/flasgger/links/3)[](https://sourcerer.io/fame/rochacbruno/rochacbruno/flasgger/links/4)[](https://sourcerer.io/fame/rochacbruno/rochacbruno/flasgger/links/5)[](https://sourcerer.io/fame/rochacbruno/rochacbruno/flasgger/links/6)[](https://sourcerer.io/fame/rochacbruno/rochacbruno/flasgger/links/7) # Examples and demo app There are some [example applications](examples/) and you can also play with examples in [Flasgger demo app](http://flasgger.pythonanywhere.com/) > NOTE: all the examples apps are also test cases and run automatically in Travis CI to ensure quality and coverage. ## Docker The examples and demo app can also be built and run as a Docker image/container: ``` docker build -t flasgger . docker run -it --rm -p 5000:5000 --name flasgger flasgger ``` Then access the Flasgger demo app at http://localhost:5000 . # Installation > under your virtualenv do: Ensure you have latest setuptools ``` pip install -U setuptools ``` then ``` pip install flasgger ``` or (dev version) ``` pip install https://github.com/rochacbruno/flasgger/tarball/master ``` > NOTE: If you want to use **Marshmallow Schemas** you also need to run `pip install marshmallow apispec` # Getting started ## Using docstrings as specification Create a file called for example `colors.py` ```python 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) ``` Now run: ``` python colors.py ``` And go to: [http://localhost:5000/apidocs/](http://localhost:5000/apidocs/) You should get:  ## Using external YAML files Save a new file `colors.yml` ```yaml 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: