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)