def openapi_format(format="yaml",
server="localhost",
no_servers=False,
return_tags=False):
extra_specs = {
'info': {
'description':
'The Faraday REST API enables you to interact with '
'[our server](https://github.com/infobyte/faraday).\n'
'Use this API to interact or integrate with Faraday'
' server. This page documents the REST API, with HTTP'
' response codes and example requests and responses.'
},
'security': {
"ApiKeyAuth": []
}
}
if not no_servers:
extra_specs['servers'] = [{'url': f'https://{server}/_api'}]
spec = APISpec(
title="Faraday API",
version="2",
openapi_version="3.0.2",
plugins=[FaradayAPIPlugin(),
FlaskPlugin(),
MarshmallowPlugin()],
**extra_specs)
api_key_scheme = {
"type": "apiKey",
"in": "header",
"name": "Authorization"
}
spec.components.security_scheme("API_KEY", api_key_scheme)
response_401_unauthorized = {
"description":
"You are not authenticated or your API key is missing "
"or invalid"
}
spec.components.response("UnauthorizedError", response_401_unauthorized)
tags = set()
with get_app().test_request_context():
for endpoint in get_app().view_functions.values():
spec.path(view=endpoint, app=get_app())
# Set up global tags
spec_yaml = yaml.load(spec.to_yaml(), Loader=yaml.SafeLoader)
for path_value in spec_yaml["paths"].values():
for data_value in path_value.values():
if 'tags' in data_value and any(data_value['tags']):
for tag in data_value['tags']:
tags.add(tag)
for tag in sorted(tags):
spec.tag({'name': tag})
if return_tags:
return sorted(tags)
if format.lower() == "yaml":
print(spec.to_yaml())
else:
print(json.dumps(spec.to_dict(), indent=2))
cors = CORS(allow_all_origins=True)
app=falcon.API(middleware=[PeeweeConnectionMW(),cors.middleware])
#consider also falcon_cors.CORS with allow_credentials_all_origins etc
spec = APISpec(
title='API Anonimizada',
version='0.9.1',
openapi_version='3.0.0', #2.0 usa consumes, 3.0 usa requestBody pero no sake muy bien en falcon_swagger_ui
info=dict(description="Modelo de API para datos anonimizados espacial y temporalmente"),
plugins=[
FalconPlugin(app),
],
)
spec.components.security_scheme("claveSimple",{"type": "http", "scheme": "basic"})
spec.tag({"name":"admin","description":"necesitan privilegios"})
spec.tag({"name":"csv","description":"fichero en CSV"})
spec.tag({"name":"open","description":"no necesita auth"})
### batch tasks, should be suitable for parallelism
def makeBatch(data,t,salt):
datalot=[]
conflictset=set()
idsKeyDict=t.idsKeys
for linetime,lineid,line in data:
#print(line,idsKeyDict)
for k in idsKeyDict:
if k in line:
if idsKeyDict[k]=="":
del line[k]
class ApiSpecPlugin(BasePlugin, DocBlueprintMixin):
"""Плагин для связки json_api и swagger"""
def __init__(self, app=None, spec_kwargs=None, decorators=None, tags: Dict[str, str] = None):
"""
:param spec_kwargs:
:param decorators:
:param tags: {'<name tag>': '<description tag>'}
"""
self.decorators_for_autodoc = decorators or tuple()
self.spec_kwargs = spec_kwargs if spec_kwargs is not None else {}
self.spec = None
self.spec_tag = {}
self.spec_schemas = {}
self.app = None
self._fields = []
# Use lists to enforce order
self._fields = []
self._converters = []
# Инициализация ApiSpec
self.app = app
self._app = app
# Initialize spec
openapi_version = app.config.get("OPENAPI_VERSION", "2.0")
openapi_major_version = int(openapi_version.split(".")[0])
if openapi_major_version < 3:
base_path = app.config.get("APPLICATION_ROOT")
# Don't pass basePath if '/' to avoid a bug in apispec
# https://github.com/marshmallow-code/apispec/issues/78#issuecomment-431854606
# TODO: Remove this condition when the bug is fixed
if base_path != "/":
self.spec_kwargs.setdefault("basePath", base_path)
self.spec_kwargs.update(app.config.get("API_SPEC_OPTIONS", {}))
self.spec = APISpec(
app.name,
app.config.get("API_VERSION", "1"),
openapi_version=openapi_version,
plugins=[MarshmallowPlugin(), RestfulPlugin()],
**self.spec_kwargs,
)
tags = tags if tags else {}
for tag_name, tag_description in tags.items():
self.spec_tag[tag_name] = {"name": tag_name, "description": tag_description, "add_in_spec": False}
self._add_tags_in_spec(self.spec_tag[tag_name])
def after_init_plugin(self, *args, app=None, **kwargs):
# Register custom fields in spec
for args in self._fields:
self.spec.register_field(*args)
# Register custom converters in spec
for args in self._converters:
self.spec.register_converter(*args)
# Initialize blueprint serving spec
self._register_doc_blueprint()
def after_route(
self,
resource: Union[ResourceList, ResourceDetail] = None,
view=None,
urls: Tuple[str] = None,
self_json_api: Api = None,
tag: str = None,
default_parameters=None,
default_schema: Schema = None,
**kwargs,
) -> None:
"""
:param resource:
:param view:
:param urls:
:param self_json_api:
:param str tag: тег под которым стоит связать этот ресурс
:param default_parameters: дефолтные поля для ресурса в сваггер (иначе просто инициализируется [])
:param Schema default_schema: схема, которая подставиться вместо схемы в стили json api
:param kwargs:
:return:
"""
# Register views in API documentation for this resource
# resource.register_views_in_doc(self._app, self.spec)
# Add tag relative to this resource to the global tag list
# We add definitions (models) to the apiscpec
if resource.schema:
self._add_definitions_in_spec(resource.schema)
# We add tags to the apiscpec
tag_name = view.title()
if tag is None and view.title() not in self.spec_tag:
dict_tag = {"name": view.title(), "description": "", "add_in_spec": False}
self.spec_tag[dict_tag["name"]] = dict_tag
self._add_tags_in_spec(dict_tag)
elif tag:
tag_name = self.spec_tag[tag]["name"]
urls = urls if urls else tuple()
for i_url in urls:
self._add_paths_in_spec(
path=i_url,
resource=resource,
default_parameters=default_parameters,
default_schema=default_schema,
tag_name=tag_name,
**kwargs,
)
@property
def param_id(self) -> dict:
return {
"in": "path",
"name": "id",
"required": True,
"type": "integer",
"format": "int32",
}
@classmethod
def _get_operations_for_all(cls, tag_name: str, default_parameters: list) -> Dict[str, Any]:
"""
Creating base dict
:param tag_name:
:param default_parameters:
:return:
"""
return {
"tags": [tag_name],
"produces": ["application/json"],
"parameters": default_parameters if default_parameters else [],
}
@classmethod
def __get_parameters_for_include_models(cls, resource: Resource) -> dict:
fields_names = [
i_field_name
for i_field_name, i_field in resource.schema._declared_fields.items()
if isinstance(i_field, Relationship)
]
models_for_include = ",".join(fields_names)
example_models_for_include = "\n".join([f"`{f}`" for f in fields_names])
return {
"default": models_for_include,
"name": "include",
"in": "query",
"format": "string",
"required": False,
"description": f"Related relationships to include.\nAvailable:\n{example_models_for_include}",
}
@classmethod
def __get_parameters_for_sparse_fieldsets(cls, resource: Resource, description: str) -> dict:
# Sparse Fieldsets
return {
"name": f"fields[{resource.schema.Meta.type_}]",
"in": "query",
"type": "array",
"required": False,
"description": description.format(resource.schema.Meta.type_),
"items": {"type": "string", "enum": list(resource.schema._declared_fields.keys())},
}
def __get_parameters_for_declared_fields(self, resource, description) -> Generator[dict, None, None]:
type_schemas = {resource.schema.Meta.type_}
for i_field_name, i_field in resource.schema._declared_fields.items():
if not (isinstance(i_field, Relationship) and i_field.schema.Meta.type_ not in type_schemas):
continue
schema_name = create_schema_name(schema=i_field.schema)
new_parameter = {
"name": f"fields[{i_field.schema.Meta.type_}]",
"in": "query",
"type": "array",
"required": False,
"description": description.format(i_field.schema.Meta.type_),
"items": {
"type": "string",
"enum": list(self.spec.components._schemas[schema_name]["properties"].keys()),
},
}
type_schemas.add(i_field.schema.Meta.type_)
yield new_parameter
@property
def __list_filters_data(self) -> tuple:
return (
{
"default": 1,
"name": "page[number]",
"in": "query",
"format": "int64",
"required": False,
"description": "Page offset",
},
{
"default": 10,
"name": "page[size]",
"in": "query",
"format": "int64",
"required": False,
"description": "Max number of items",
},
{"name": "sort", "in": "query", "format": "string", "required": False, "description": "Sort",},
{
"name": "filter",
"in": "query",
"format": "string",
"required": False,
"description": "Filter (https://flask-combo-jsonapi.readthedocs.io/en/latest/filtering.html)",
},
)
@classmethod
def _update_parameter_for_field_spec(cls, new_param: dict, fld_sped: dict) -> None:
"""
:param new_param:
:param fld_sped:
:return:
"""
if "items" in fld_sped:
new_items = {
"type": fld_sped["items"].get("type"),
}
if "enum" in fld_sped["items"]:
new_items["enum"] = fld_sped["items"]["enum"]
new_param.update({"items": new_items})
def __get_parameter_for_not_nested(self, field_name, field_spec) -> dict:
new_parameter = {
"name": f"filter[{field_name}]",
"in": "query",
"type": field_spec.get("type"),
"required": False,
"description": f"{field_name} attribute filter",
}
self._update_parameter_for_field_spec(new_parameter, field_spec)
return new_parameter
def __get_parameter_for_nested_with_filtering(self, field_name, field_jsonb_name, field_jsonb_spec):
new_parameter = {
"name": f"filter[{field_name}{SPLIT_REL}{field_jsonb_name}]",
"in": "query",
"type": field_jsonb_spec.get("type"),
"required": False,
"description": f"{field_name}{SPLIT_REL}{field_jsonb_name} attribute filter",
}
self._update_parameter_for_field_spec(new_parameter, field_jsonb_spec)
return new_parameter
def __get_parameters_for_nested_with_filtering(self, field, field_name) -> Generator[dict, None, None]:
# Allow JSONB filtering
field_schema_name = create_schema_name(schema=field.schema)
component_schema = self.spec.components._schemas[field_schema_name]
for i_field_jsonb_name, i_field_jsonb in field.schema._declared_fields.items():
i_field_jsonb_spec = component_schema["properties"][i_field_jsonb_name]
if i_field_jsonb_spec.get("type") == "object":
# Пропускаем создание фильтров для dict. Просто не понятно как фильтровать по таким
# полям
continue
new_parameter = self.__get_parameter_for_nested_with_filtering(
field_name, i_field_jsonb_name, i_field_jsonb_spec,
)
yield new_parameter
def __get_list_resource_fields_filters(self, resource) -> Generator[dict, None, None]:
schema_name = create_schema_name(schema=resource.schema)
for i_field_name, i_field in resource.schema._declared_fields.items():
i_field_spec = self.spec.components._schemas[schema_name]["properties"][i_field_name]
if not isinstance(i_field, fields.Nested):
if i_field_spec.get("type") == "object":
# Skip filtering by dicts
continue
yield self.__get_parameter_for_not_nested(i_field_name, i_field_spec)
elif getattr(i_field.schema.Meta, "filtering", False):
yield from self.__get_parameters_for_nested_with_filtering(i_field, i_field_name)
def _get_operations_for_get(self, resource, tag_name, default_parameters):
operations_get = self._get_operations_for_all(tag_name, default_parameters)
operations_get["responses"] = {
**status[HTTPStatus.OK],
**status[HTTPStatus.NOT_FOUND],
}
if issubclass(resource, ResourceDetail):
operations_get["parameters"].append(self.param_id)
if resource.schema is None:
return operations_get
description = "List that refers to the name(s) of the fields to be returned `{}`"
operations_get["parameters"].extend(
(
self.__get_parameters_for_include_models(resource),
self.__get_parameters_for_sparse_fieldsets(resource, description),
)
)
operations_get["parameters"].extend(self.__get_parameters_for_declared_fields(resource, description))
if issubclass(resource, ResourceList):
operations_get["parameters"].extend(self.__list_filters_data)
operations_get["parameters"].extend(self.__get_list_resource_fields_filters(resource))
return operations_get
def _get_operations_for_post(self, schema: dict, tag_name: str, default_parameters: list) -> dict:
operations = self._get_operations_for_all(tag_name, default_parameters)
operations["responses"] = {
"201": {"description": "Created"},
"202": {"description": "Accepted"},
"403": {"description": "This implementation does not accept client-generated IDs"},
"404": {"description": "Not Found"},
"409": {"description": "Conflict"},
}
operations["parameters"].append(
{
"name": "POST body",
"in": "body",
"schema": schema,
"required": True,
"description": f"{tag_name} attributes",
}
)
return operations
def _get_operations_for_patch(self, schema: dict, tag_name: str, default_parameters: list) -> dict:
operations = self._get_operations_for_all(tag_name, default_parameters)
operations["responses"] = {
"200": {"description": "Success"},
"201": {"description": "Created"},
"204": {"description": "No Content"},
"403": {"description": "Forbidden"},
"404": {"description": "Not Found"},
"409": {"description": "Conflict"},
}
operations["parameters"].append(self.param_id)
operations["parameters"].append(
{
"name": "POST body",
"in": "body",
"schema": schema,
"required": True,
"description": f"{tag_name} attributes",
}
)
return operations
def _get_operations_for_delete(self, tag_name: str, default_parameters: list) -> dict:
operations = self._get_operations_for_all(tag_name, default_parameters)
operations["parameters"].append(self.param_id)
operations["responses"] = {
"200": {"description": "Success"},
"202": {"description": "Accepted"},
"204": {"description": "No Content"},
"403": {"description": "Forbidden"},
"404": {"description": "Not Found"},
}
return operations
def _add_paths_in_spec(
self,
path: str = "",
resource: Any = None,
tag_name: str = "",
default_parameters: List = None,
default_schema: Schema = None,
**kwargs,
) -> None:
operations = {}
methods: Set[str] = {i_method.lower() for i_method in resource.methods}
attributes = {}
if resource.schema:
attributes = {"$ref": f"#/definitions/{create_schema_name(resource.schema)}"}
schema = (
default_schema
if default_schema
else {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"type": {
"type": "string",
},
"id": {
"type": "string",
},
"attributes": attributes,
"relationships": {
"type": "object",
},
},
"required": [
"type",
],
},
},
}
)
if "get" in methods:
operations["get"] = self._get_operations_for_get(resource, tag_name, default_parameters)
if "post" in methods:
operations["post"] = self._get_operations_for_post(schema, tag_name, default_parameters)
if "patch" in methods:
operations["patch"] = self._get_operations_for_patch(schema, tag_name, default_parameters)
if "delete" in methods:
operations["delete"] = self._get_operations_for_delete(tag_name, default_parameters)
rule = None
for i_rule in self.app.url_map._rules:
if i_rule.rule == path:
rule = i_rule
break
if APISPEC_VERSION_MAJOR < 1:
self.spec.add_path(path=path, operations=operations, rule=rule, resource=resource, **kwargs)
else:
self.spec.path(path=path, operations=operations, rule=rule, resource=resource, **kwargs)
def _add_definitions_in_spec(self, schema) -> None:
"""
Add schema in spec
:param schema: schema marshmallow
:return:
"""
name_schema = create_schema_name(schema)
if name_schema not in self.spec_schemas and name_schema not in self.spec.components._schemas:
self.spec_schemas[name_schema] = schema
if APISPEC_VERSION_MAJOR < 1:
self.spec.definition(name_schema, schema=schema)
else:
self.spec.components.schema(name_schema, schema=schema)
def _add_tags_in_spec(self, tag: Dict[str, str]) -> None:
"""
Add tags in spec
:param tag: {'name': '<name tag>', 'description': '<tag description>', 'add_in_spec': <added tag in spec?>}
:return:
"""
if tag.get("add_in_spec", True) is False:
self.spec_tag[tag["name"]]["add_in_spec"] = True
tag_in_spec = {"name": tag["name"], "description": tag["description"]}
if APISPEC_VERSION_MAJOR < 1:
self.spec.add_tag(tag_in_spec)
else:
self.spec.tag(tag_in_spec)
def generate_spec(request, swagger_info, plugins, filter_by_tags=False):
"""Generate OpenAPI Spec.
This function will start the route introspection in Pyramid,
looking for views with the following cornice_apispec and cornice predicates:
* `schema`: Cornice predicate for Schema validator
* `content_type`: Cornice/Pyramid predicate for Content-Type
* `apispec_response_schemas`: (List) Response Schemas to add in Swagger
* `apispec_tags`: (List) Tag List for view
* `apispec_summary`: (Str) Short Summary for view operation in swagger
* `apispec_description`: (Str) Long description for view operation in swagger
* `apispec_show`: (Bool) Only views with this predicate will be included in Swagger
Examples
^^^^^^^^
## Pyramid::
@view_config(
apispec_tags=['health'],
apispec_summary="Returns healthcheck',
apispec_description="Long description for operation",
apispec_show=True)
def health_check(request):
request.response.status = 200
request.response.body = "OK"
return request.response
## Cornice Service::
health_chech_service = Service(
name='healthcheck_api',
description='API HealthCheck',
path="/health",
apispec_show=True,
apispec_tags=['health']
)
@health_chech_service.get(
apispec_description="Long description for operation")
def health_check(request):
request.response.status = 200
request.response.body = "OK"
return request.response
For more examples, please see ./examples folder.
swagger_info options
^^^^^^^^^^^^^^^^^^^^
* `title`: Api Title (default: 'OpenAPI Docs')
* `main_description`: Main description for API. Accepts Markdown. (Default: '')
* `version`: Api Version (default: '0.1.0')
* `openapi_version`: OpenAPI version (default: '3.0.2')
* `show_head`: Show HEAD requests in Swagger (default: False)
* `show_options`: Show OPTIONS requests in Swagger (default: True)
* `tag_list`: Tag dict list. No defaults.
(example: [{'name': 'my tag', 'description': 'my description'}]).
* `scheme`: http or https. If not informed, will extract from request.
The `filter_by_tags` option will filter all views which does not have at
least one tag from swagger_info tag_list.
:param request: Pyramid Request
:param swagger_info: Dict
:param plugins: APISpec Plugins list
:param filter_by_tags: Show only views with tags inside tag_list
:return: Dict
"""
def check_tag(view):
if not filter_by_tags:
return True
view_tags = view['introspectable'].get('apispec_tags', [])
openapi_tags = [tag['name'] for tag in spec._tags]
if not view_tags:
return False
for tag in view_tags:
if tag in openapi_tags:
return True
return False
spec = APISpec(
title=swagger_info.get('title', "OpenAPI Docs"),
version=swagger_info.get('version', '0.1.0'),
plugins=[plugin() for plugin in plugins],
openapi_version=swagger_info.get('openapi_version', '3.0.2')
)
for tag in swagger_info.get('tag_list', []):
spec.tag(tag)
for view in request.registry.introspector.get_category('views'):
show_apispec = view['introspectable'].get('apispec_show', False) is True
has_request_methods = view['introspectable'].get('request_methods')
has_tag = check_tag(view)
if show_apispec and has_request_methods and has_tag:
add_pyramid_paths(
spec, view['introspectable'].get('route_name'),
request=request,
show_head=swagger_info.get('show_head', False),
show_options=swagger_info.get('show_options', True)
)
openapi_spec = spec.to_dict()
main_description = swagger_info.get('main_description', "")
if main_description:
openapi_spec['info'].update({'description': main_description})
scheme = swagger_info.get('scheme', request.scheme)
main_server_url = '{}://{}'.format(scheme, request.host)
logger.info('Server URL for swagger json is {}'.format(main_server_url))
openapi_spec.update({'servers': [{'url': main_server_url}]})
return openapi_spec
msg = fields.String(description="A message.", required=True)
# register schemas with spec
spec.components.schema("Input", schema=InputSchema)
spec.components.schema("Output", schema=OutputSchema)
# add swagger tags that are used for endpoint annotation
tags = [
{
'name': 'testing',
'description': 'For testing the API.'
},
{
'name': 'Credentials',
'description': 'Functions for credentials.'
},
{
'name': 'auth',
'description': 'Functions for Authentification in ika Web.'
},
{
'name': 'google Gmail API',
'description': 'Functions for using Gmail API.'
},
]
for tag in tags:
print(f"Adding tag: {tag['name']}")
spec.tag(tag)
