def autodoc(fn):
if isinstance(fn, type):
for name in fn.__dict__:
attr = getattr(fn, name)
if callable(attr) and name in ('get', 'put', 'post', 'patch',
'delete'):
attr.__owner__ = fn
setattr(fn, name, autodoc(attr))
if fn.__doc__:
parsed_doc = parse_doc(fn)
return doc(**parsed_doc)(fn)
elif callable(fn):
parsed_doc = parse_doc(fn)
return doc(**parsed_doc)(fn)
return fn
def swagger_spec(cls, swagger_desc, api_schema, tag):
doc_decorator = doc(description=swagger_desc, tags=tag)
doc_use_kwargs = use_kwargs(api_schemas.get(api_schema),
location=('json'))
cls = doc_decorator(cls)
cls = doc_use_kwargs(cls)
return cls
def decorator(fn):
params = {}
for k, v in kwargs.items():
if isinstance(v, str):
params[k] = {'description': v}
elif isinstance(v, dict):
params[k] = v
return doc(params=params)(fn)
def load_docs(app: Flask):
"""
Function for creating api docs using ``flask-apispec``.
"""
if not app.config.get("API_DOCS", False):
return
import_name = get_import_name(app)
docs: FlaskApiSpec = import_attr(import_name + "extensions.apispec.docs")
urls = import_module(import_name + "urls")
api_docs = urls.docs
routes = urls.routes
for _, view, _ in routes:
if api_docs:
view = doc(**api_docs)(view)
docs.register(view)
apis = app.config.get("APIS", [])
for res in apis:
res = import_module(import_name + res)
api_docs = res.docs
routes = res.routes
endpoint = res.endpoint
for detail in routes:
_, view, _ = detail
e = endpoint + "_" + view.__name__
if api_docs:
view = doc(**api_docs)(view)
docs.register(view, endpoint=e, blueprint="api")
blueprints = app.config.get("BLUEPRINTS", [])
for name in blueprints:
bp = import_name + name + ".routes.blueprint"
bp: Blueprint = import_attr(bp)
urls = import_name + name + ".urls"
urls = import_module(urls)
api_docs = urls.docs
routes = urls.routes
for _, view, _ in routes:
if api_docs:
view = doc(**api_docs)(view)
docs.register(view, blueprint=name)
def authdoc(inherit=None, **kwargs):
return doc(params={
"Authorization": {
"description": "Authorization (add Bearer) to string",
"in": "header",
"type": "string",
"required": True
}
},
inherit=inherit,
**kwargs)
def header_doc(description, tags=()):
"""Wrap additional OpenAPI header description for an endpoint."""
return doc(
description=description,
params={
"Authorization": {
"description": ("Used for users git oauth2 access. "
"For example: "
"```Authorization: Bearer asdf-qwer-zxcv```"),
"in":
"header",
"type":
"string",
"required":
True,
},
"Renku-User-Id": {
"description":
("Used for identification of the users. "
"For example: "
"```Renku-User-Id: sasdsa-sadsd-gsdsdh-gfdgdsd```"),
"in":
"header",
"type":
"string",
"required":
True,
},
"Renku-User-FullName": {
"description": ("Used for commit author signature. "
"For example: "
"```Renku-User-FullName: Rok Roskar```"),
"in":
"header",
"type":
"string",
"required":
True,
},
"Renku-User-Email": {
"description": ("Used for commit author signature. "
"For example: "
"```Renku-User-Email: [email protected]```"),
"in":
"header",
"type":
"string",
"required":
True,
},
},
tags=list(tags),
)
def header_doc(description, tags=()):
"""Wrap additional OpenAPI header description for an endpoint."""
return doc(
description=description,
params={
'Authorization': {
'description': ('Used for users git oauth2 access. '
'For example: '
'```Authorization: Bearer asdf-qwer-zxcv```'),
'in':
'header',
'type':
'string',
'required':
True
},
'Renku-User-Id': {
'description':
('Used for identification of the users. '
'For example: '
'```Renku-User-Id: sasdsa-sadsd-gsdsdh-gfdgdsd```'),
'in':
'header',
'type':
'string',
'required':
True
},
'Renku-User-FullName': {
'description': ('Used for commit author signature. '
'For example: '
'```Renku-User-FullName: Rok Roskar```'),
'in':
'header',
'type':
'string',
'required':
True
},
'Renku-User-Email': {
'description': ('Used for commit author signature. '
'For example: '
'```Renku-User-Email: [email protected]```'),
'in':
'header',
'type':
'string',
'required':
True
},
},
tags=list(tags),
)
def register_rules(app, resources):
for resource in resources:
for func_name in (d for d in dir(resource) if not d.startswith('__')):
func = getattr(resource, func_name)
if hasattr(func, '__url__') and hasattr(func, '__method__'):
func_url = func.__url__
func_method = func.__method__
func_name = func.__name__
not_in_prod_doc = func.__not_in_prod_doc__
doc_opts = {}
if hasattr(func, '__docs__'):
doc_opts = {
**func.__docs__, 'tags': [
resource.default_tag,
*func.__docs__.get('tags', []),
]
}
func = doc(**doc_opts)(func)
endpoint = '{}.{}'.format(resource.__name__, func_name)
app.add_url_rule(
resource.base_url + func_url,
endpoint=endpoint,
view_func=func,
methods=func_method,
strict_slashes=False,
)
is_dev = app.config['FLASK_ENV'] == 'development'
if is_dev or (is_dev == False and not_in_prod_doc == False):
app.__docs__.register(func, endpoint=endpoint)
for key, value in app.__docs__.spec._paths.items():
app.__docs__.spec._paths[key] = {
inner_key: inner_value
for inner_key, inner_value in value.items()
if inner_key != 'options'
}
def wrapper(func: Callable):
d = kwds.pop("description", func.__doc__ or "")
kwds["description"] = d
func = doc(**kwds)(func)
return func
def tag(*tag):
return doc(tags=[*tag])
def op_id(op_id):
return doc(operationId=op_id)
def auth_required(security):
return doc(security=[{security: []}])
