fl_server_api.openapi ¶

class BasicAuthAllowingTokenAuthInUrlScheme(BasicScheme):
    """
    A class that extends the BasicScheme to allow token authentication in the URL.
    """

    target_class = "fl_server_api.views.base.BasicAuthAllowingTokenAuthInUrl"
    priority = 0

class CustomAutoSchema(AutoSchema):
    """
    A custom AutoSchema that includes the documented examples from the Docstrings in the description.
    """

    show_examples = True
    """Flag to include examples in the description."""
    rendering_style = RenderingStyle.CLEAN
    """Docstring rendering style."""

    def _get_docstring(self):
        """
        Get the docstring of the view.

        This method parses the description of the view.

        Returns:
            Docstring: The parsed docstring.
        """
        return parse(super().get_description())

    def _get_param_docstring(self, docstring: Docstring, argument: str) -> Optional[str]:
        """
        Get the docstring of a parameter.

        This method finds the parameter in the docstring and returns its description.

        Args:
            docstring (Docstring): The docstring.
            argument (str): The name of the argument.

        Returns:
            Optional[str]: The description of the argument, or `None` if the argument is not found.
        """
        params = [p for p in docstring.params if p.arg_name == argument]
        if not params:
            return None
        return params[0].description

    def get_description(self):
        """
        Get the description of the view including its examples (if desired) formatted as markdown.

        Returns:
            str: The description of the view as markdown.
        """
        docstring = self._get_docstring()
        tmp_docstring = Docstring(style=docstring.style)
        tmp_docstring.short_description = docstring.short_description
        tmp_docstring.long_description = docstring.long_description
        if self.show_examples:
            tmp_docstring.meta.extend(docstring.examples)
        desc = compose(tmp_docstring, self.rendering_style, indent="")
        if self.show_examples and desc.__contains__("Examples:"):
            # customize examples section:
            # - examples should be in a new paragraph (not concatenated with the description)
            # - the examples header should be a h3 title
            desc = desc.replace("\nExamples:\n", "\n\n### Examples:\n\n")
        desc = cleandoc(desc)
        return desc

    def _resolve_path_parameters(self, variables: List[str]):
        """
        Resolve the path parameters of the view and set their descriptions if they are missing.

        Args:
            variables (List[str]): The list of variables in the path.

        Returns:
            list: The list of path parameters.
        """
        parameters = super()._resolve_path_parameters(variables)
        docstring = self._get_docstring()
        for parameter in parameters:
            if "description" not in parameter:
                description = self._get_param_docstring(docstring, parameter["name"])
                if description:
                    parameter["description"] = description
        return parameters

    def get_operation_id(self):
        """
        Get the operation ID which is the fully qualified name of the corresponding view/action/method.

        Returns:
            str: The operation ID.
        """
        action_or_method = getattr(self.view, getattr(self.view, 'action', self.method.lower()), None)
        return fullname(action_or_method or self.view.__class__)