OpenAPI

add_response(operation, status_code, schema, description, example=None, examples=None, links=None)

Add response to operation.

Version changed: 0.10.0

• Add links parameter.

Source code in apiflask/openapi.py

def add_response(
    operation: dict,
    status_code: str,
    schema: t.Union[SchemaType, dict],
    description: str,
    example: t.Optional[t.Any] = None,
    examples: t.Optional[t.Dict[str, t.Any]] = None,
    links: t.Optional[t.Dict[str, t.Any]] = None,
) -> None:
    """Add response to operation.

    *Version changed: 0.10.0*

    - Add `links` parameter.
    """
    operation['responses'][status_code] = {}
    if status_code != '204':
        operation['responses'][status_code]['content'] = {
            'application/json': {
                'schema': schema
            }
        }
    operation['responses'][status_code]['description'] = description
    if example is not None:
        operation['responses'][status_code]['content'][
            'application/json']['example'] = example
    if examples is not None:
        operation['responses'][status_code]['content'][
            'application/json']['examples'] = examples
    if links is not None:
        operation['responses'][status_code]['links'] = links

add_response_with_schema(spec, operation, status_code, schema, schema_name, description)

Add response with given schema to operation.

Source code in apiflask/openapi.py

def add_response_with_schema(
    spec: APISpec,
    operation: dict,
    status_code: str,
    schema: OpenAPISchemaType,
    schema_name: str,
    description: str
) -> None:
    """Add response with given schema to operation."""
    if isinstance(schema, type):
        schema = schema()
        add_response(operation, status_code, schema, description)
    elif isinstance(schema, dict):
        if schema_name not in spec.components.schemas:
            spec.components.schema(schema_name, schema)
        schema_ref = {'$ref': f'#/components/schemas/{schema_name}'}
        add_response(operation, status_code, schema_ref, description)
    else:
        raise TypeError(_bad_schema_message)

get_argument(argument_type, argument_name)

Make argument from given type and name.

Source code in apiflask/openapi.py

def get_argument(argument_type: str, argument_name: str) -> t.Dict[str, t.Any]:
    """Make argument from given type and name."""
    argument: t.Dict[str, t.Any] = {
        'in': 'path',
        'name': argument_name,
    }
    if argument_type == 'int:':
        argument['schema'] = {'type': 'integer'}
    elif argument_type == 'float:':
        argument['schema'] = {'type': 'number'}
    else:
        argument['schema'] = {'type': 'string'}
    return argument

get_auth_name(auth, auth_names)

Get auth name from auth object.

Source code in apiflask/openapi.py

def get_auth_name(
    auth: HTTPAuthType,
    auth_names: t.List[str]
) -> str:
    """Get auth name from auth object."""
    name: str
    if isinstance(auth, HTTPBasicAuth):
        name = 'BasicAuth'
    elif isinstance(auth, HTTPTokenAuth):
        if auth.scheme.lower() == 'bearer' and auth.header is None:
            name = 'BearerAuth'
        else:
            name = 'ApiKeyAuth'
    else:
        raise TypeError('Unknown authentication scheme.')
    if name in auth_names:
        v = 2
        new_name = f'{name}_{v}'
        while new_name in auth_names:
            v += 1
            new_name = f'{name}_{v}'
        name = new_name
    return name

get_operation_tags(blueprint, blueprint_name)

Get operation tag from blueprint object.

Source code in apiflask/openapi.py

def get_operation_tags(
    blueprint: APIBlueprint,
    blueprint_name: str
) -> t.List[str]:
    """Get operation tag from blueprint object."""
    tags: t.List[str]
    if blueprint.tag is not None:
        if isinstance(blueprint.tag, dict):
            tags = [blueprint.tag['name']]
        else:
            tags = [blueprint.tag]
    else:
        tags = [blueprint_name.title()]
    return tags

get_path_description(func)

Get path description from the docstring of the view function.

Source code in apiflask/openapi.py

def get_path_description(func: t.Callable) -> str:
    """Get path description from the docstring of the view function."""
    docs = (func.__doc__ or '').strip().split('\n')
    if len(docs) > 1:
        # use the remain lines of docstring as description
        return '\n'.join(docs[1:]).strip()
    return ''

get_path_summary(func, fallback=None)

Get path summary from the name or docstring of the view function.

Source code in apiflask/openapi.py

def get_path_summary(func: t.Callable, fallback: t.Optional[str] = None) -> str:
    """Get path summary from the name or docstring of the view function."""
    summary: str
    docs: list = (func.__doc__ or '').strip().split('\n')
    if docs[0]:
        # Use the first line of docstring
        summary = docs[0]
    else:
        # Use the function name
        summary = fallback or ' '.join(func.__name__.split('_')).title()
    return summary

get_security_and_security_schemes(auth_names, auth_schemes)

Make security and security schemes from given auth names and schemes.

Source code in apiflask/openapi.py

def get_security_and_security_schemes(
    auth_names: t.List[str],
    auth_schemes: t.List[HTTPAuthType]
) -> t.Tuple[t.Dict[HTTPAuthType, str], t.Dict[str, t.Dict[str, str]]]:
    """Make security and security schemes from given auth names and schemes."""
    security: t.Dict[HTTPAuthType, str] = {}
    security_schemes: t.Dict[str, t.Dict[str, str]] = {}
    for name, auth in zip(auth_names, auth_schemes):  # noqa: B905
        security[auth] = name
        security_schemes[name] = get_security_scheme(auth)
        if hasattr(auth, 'description') and auth.description is not None:
            security_schemes[name]['description'] = auth.description
    return security, security_schemes

get_security_scheme(auth)

Get security scheme from auth object.

Source code in apiflask/openapi.py

def get_security_scheme(auth: HTTPAuthType) -> t.Dict[str, t.Any]:
    """Get security scheme from auth object."""
    security_scheme: t.Dict[str, t.Any]
    if isinstance(auth, HTTPTokenAuth):
        if auth.scheme.lower() == 'bearer' and auth.header is None:
            security_scheme = {
                'type': 'http',
                'scheme': 'bearer',
            }
        else:
            security_scheme = {
                'type': 'apiKey',
                'name': auth.header,
                'in': 'header',
            }
    else:
        security_scheme = {
            'type': 'http',
            'scheme': 'basic',
        }
    return security_scheme

get_tag(blueprint, blueprint_name)

Get tag from blueprint object.

Source code in apiflask/openapi.py

def get_tag(
    blueprint: APIBlueprint,
    blueprint_name: str
) -> t.Dict[str, t.Any]:
    """Get tag from blueprint object."""
    tag: t.Dict[str, t.Any]
    if blueprint.tag is not None:
        if isinstance(blueprint.tag, dict):
            tag = blueprint.tag
        else:
            tag = {'name': blueprint.tag}
    else:
        tag = {'name': blueprint_name.title()}
    return tag