utils.py: backward condition silently drops single-line docstring descriptions; HEAD/OPTIONS methods silently ignored

[pramodavansaber]

Hi luolingchun — found three issues in flask_openapi/utils.py while running adversarial test generation via tailtest. All three are small fixes.

1. get_operation line 58 — backward condition swallows single-line docstring descriptions

doc_description = lines[0] if len(lines) == 0 else "<br/>".join(lines[1:])

doc.split("\n") always returns at least 1 element, so len(lines) == 0 is always False. When a function has a single-line docstring with no explicit summary, doc_description becomes "<br/>".join([]) = "". The description is silently lost from the generated OpenAPI spec.

Suspected intent: len(lines) <= 1 (use the line as description if there's only one).

2. parse_method silently drops HTTPMethod.HEAD

The if/elif ladder handles GET/POST/PUT/PATCH/DELETE. HEAD operations are valid HTTP and the PathItem model has a head field, but routes registered with methods=["HEAD"] are silently dropped — no PathItem entry, no warning.

Fix: add elif method == HTTPMethod.HEAD: paths.setdefault(uri, PathItem()).head = operation

3. parse_method silently drops HTTPMethod.OPTIONS

Same issue as #2 for OPTIONS — PathItem has the field but the parser doesn't populate it.

Reproduction

import pytest
from flask_openapi.models.api_doc import PathItem
from flask_openapi.models.operation import Operation
from flask_openapi.utils import get_operation, parse_method
from flask_openapi.types import HTTPMethod


# Bug 1
def test_single_line_docstring_description_should_not_vanish():
    """get_operation: single-line docstring should NOT lose description.

    Reproduction:
    - Define a function with a single-line docstring (no blank-line separator)
    - Call get_operation(func) without explicit summary kwarg
    - Expected: doc_description == the single docstring line
    - Observed: doc_description == "" (silently lost)
    """
    def my_endpoint():
        """A single-line description."""
        pass
    op = get_operation(my_endpoint)
    assert op.description == "A single-line description.", (
        f"Description silently lost; got: {op.description!r}"
    )


# Bug 2
def test_head_method_silently_ignored():
    """parse_method: HEAD operation should be added to PathItem."""
    paths = {}
    op = Operation(summary="test")
    parse_method("/test", HTTPMethod.HEAD, paths, op)
    assert "/test" in paths, "HEAD method silently ignored by parse_method"


# Bug 3
def test_options_method_silently_ignored():
    """parse_method: OPTIONS operation should be added to PathItem."""
    paths = {}
    op = Operation(summary="test")
    parse_method("/test", HTTPMethod.OPTIONS, paths, op)
    assert "/test" in paths, "OPTIONS method silently ignored by parse_method"

Happy to open a PR if useful. Found via tailtest.

[luolingchun]

@pramodavansaber Thank you for your work, small fixes can make this project more perfect.

Issue 1 can be submitted as a separate PR.

Regarding issues 2 and 3, the official Flask currently only implements 5 shortcuts: GET, POST, PUT, DELETE, PATCH. I'm not sure if it supports independent HEAD, OPTIONS, TRACE. If you are interested, you can draft a PR to address this issue.

[pramodavansaber]

Thanks @luolingchun, appreciate the response.

Will draft a PR for issue 1 (the get_operation backward condition) in the coming days. Should be a one-line change plus a test that asserts a single-line summary survives the OpenAPI generation step.

On issues 2 and 3 (HEAD and OPTIONS): you're right that Flask only ships convenience shortcuts for GET / POST / PUT / DELETE / PATCH on the Flask and Blueprint classes. But Flask routes do support both methods through methods= on @app.route(...) and via add_url_rule(...). Spec-wise, OpenAPI 3.x defines HEAD and OPTIONS as standard PathItem operations, so picking them up in the generator matches the spec rather than mirroring Flask's shortcut surface.

Happy to draft a PR for that if you want it scoped that way (handle HEAD and OPTIONS in parse_method; leave TRACE alone since it is not part of standard OpenAPI 3.x). Let me know if you would prefer it as a single PR with issue 1 or two separate PRs.

Filed via tailtest running adversarial test scenarios.

[luolingchun]

1. get_operation line 58 — backward condition silently drops single-line docstring descriptions

This issue will be fixed in #264 .