Source code for flask_swag


Flask extension that extracts swagger spec from flask app & provides
Swagger UI.

import os
import urllib.parse

from flask import Flask, Blueprint, current_app, jsonify, \
    send_from_directory, url_for, request, redirect

from . import core
from .extractor import Extractor, MarkExtractor
from .globals import SWAGGER_UI_DIR
from .mark import Mark
from .version import VERSION

__version__ = VERSION

[docs]class Swag(object): """ Flask extension class for flask_swag. This is plain flask extension. So, you can use it like :: swag = Swag(app) and also :: swag = Swag(app) # Init later swag.init_app(app) The extension requires following configurations. * SWAG_TITLE Title for swagger info. * SWAG_API_VERSION API version info. Or you can provide `core.Info` instead of them. To customize URL for swagger, use following configurations. * SWAG_BLUEPRINT_NAME Default is ``'swag'`` * SWAG_URL_PREFIX Default is ``'/swagger'`` * SWAG_JSON_URL Default is ``'/swagger.json'`` * SWAG_UI_PREFIX Default is ``'/ui'`` And you can use another version of swagger-ui using configuration. * SWAG_UI_ROOT """ def __init__(self, app: Flask=None, extractor: Extractor=None, mark: Mark=None, *args, **kwargs): """ :param app: app to be initialized :param extractor: extractor instance, default is :class:`.extractor.MarkExtractor` :param extractor: marker instance, default is :class:`.mark.Mark` :param \*args: args to be passed to :meth:`init_app` :param \*\*kwargs: kwargs to be passed to :meth:`init_app` """ = app self.extractor = extractor or MarkExtractor() self.mark = mark or Mark() if app is not None: self.init_app(app, *args, **kwargs)
[docs] def init_app(self, app, swagger_info=None, swagger_fields=None): """Init flask app for Flask-Swag.""" # Default values for configurations app.config.setdefault('SWAG_UI_ROOT', SWAGGER_UI_DIR) app.config.setdefault('SWAG_BLUEPRINT_NAME', 'swag') app.config.setdefault('SWAG_URL_PREFIX', '/swagger') app.config.setdefault('SWAG_JSON_URL', '/swagger.json') app.config.setdefault('SWAG_UI_PREFIX', '/ui') # Add generator too app def generate_swagger(): return self.generate_swagger(app, swagger_info, swagger_fields) app.generate_swagger = generate_swagger self.register_blueprint(app)
[docs] def generate_swagger(self, app: Flask=current_app, swagger_info=None, swagger_fields=None, swag_blueprint='swag', extractor_kwargs=None): """ Generate swagger spec from `app`. :param app: the flask app. :param swagger_info: `info` field in swagger root object. :param swagger_fields: extra fields in swagger root object. :param swag_blueprint: the name of Flask-Swag blueprint :extractor_kwargs: kwargs to be passed to extractor's :meth:`extract_paths` """ # Normalize args swagger_fields = swagger_fields or {} swagger_info = swagger_info or core.Info( title=app.config['SWAG_TITLE'], version=app.config['SWAG_API_VERSION'], ) # Extract info from current request parsed = urllib.parse.urlparse(request.host_url) schemes = [parsed.scheme] host = parsed.netloc # Extract paths from app ex_kwargs = { 'exclude_blueprint': swag_blueprint, } ex_kwargs.update(extractor_kwargs or {}) paths = self.extractor.extract_paths(app, **ex_kwargs) # Build kwargs for core.Swagger kwargs = { 'info': swagger_info, 'host': host, 'schemes': schemes, 'version': "2.0", 'paths': paths, } # Update with swagger_fields kwargs.update(swagger_fields) return core.dump(core.Swagger(**kwargs))
[docs] def inject_swagger_url(self, html, url): """ Change default swagger URL by injecting javascript code into html. """ js = """ $(function() {{ window.swaggerUi.updateSwaggerUi({{ url: '{url}', apiKey: '' }}); }}); """.format(url=url) tag = '<script type="text/javascript">{js}</script>'.format( js=js ) components = html.rsplit('</body>', 1) if len(components) == 1: html, = components components = html.rsplit('</html>', 1) if len(components) == 1: html = html + tag else: first, rest = components html = first + tag + '</html>' + rest else: first, rest = components html = first + tag + '</body>' + rest return html
[docs] def make_blueprint(self, blueprint_name, swagger_ui_root, json_url, ui_prefix) -> Blueprint: """ Create a new Swagger UI related blueprint. :param blueprint_name: name of the blueprint. default is `'swag'` :param swagger_ui_root: root path for swagger-ui. :param json_url: swagger spec json URL. :param ui_prefix: prefix URL for swagger-ui """ blueprint = Blueprint(blueprint_name, __name__) @blueprint.route(json_url) def swagger_json(): swagger = current_app.generate_swagger() return jsonify(swagger) @blueprint.route('{}/<path:path>'.format(ui_prefix)) def swagger_ui(path): return send_from_directory(swagger_ui_root, path, cache_timeout=3600) @blueprint.route('{}/'.format(ui_prefix)) def swagger_ui_index(): with open(os.path.join(swagger_ui_root, 'index.html')) as f: html = # Inject javascript code url = url_for('{}.swagger_json'.format(blueprint_name)) html = self.inject_swagger_url(html, url) return html, 200 @blueprint.route(ui_prefix) def swagger_ui_prefix(): return redirect('{}.swagger_ui_index'.format(blueprint_name)) return blueprint
[docs] def register_blueprint(self, app: Flask) \ -> Blueprint: """ Register Swagger UI related blueprint. :param blueprint_name: name of the blueprint. default is `'swag'` :param prefix: URL prefix of the blueprint. :returns: created blueprint """ prefix = app.config['SWAG_URL_PREFIX'] blueprint_name = app.config['SWAG_BLUEPRINT_NAME'] swagger_ui_root = app.config['SWAG_UI_ROOT'] json_url = app.config['SWAG_JSON_URL'] ui_prefix = app.config['SWAG_UI_PREFIX'] blueprint = self.make_blueprint(blueprint_name, swagger_ui_root, json_url, ui_prefix) app.register_blueprint(blueprint, url_prefix=prefix) return blueprint