Improve Error Message Specificity for Incorrect YAML
- Dominant language
- Python
- Stars
- 3.7k
- Forks
- 525
- PR merge metrics
- No merged PRs in 30d
Description
When methods have documentation that is poorly-formatted or contains syntax errors in an otherwise-working Flask project, going to the `/apidocs` endpoint produces a very long series of error messages in unparsed HTML:

The accompanying error messages (a stack trace 30-deep) on the webserver hosting it all aren't much more helpful in finding what's wrong:
```
Traceback (most recent call last):
File "/usr/local/lib/python2.7/dist-packages/flask/app.py", line 2309, in __call__
return self.wsgi_app(environ, start_response)
...
...
File "/usr/local/lib/python2.7/dist-packages/flask/views.py", line 158, in dispatch_request
return meth(*args, **kwargs)
File "/usr/local/lib/python2.7/dist-packages/flasgger/base.py", line 187, in get
optional_fields, self.process_doc)
File "/usr/local/lib/python2.7/dist-packages/flasgger/utils.py", line 114, in get_specs
method, sanitizer, endpoint=rule.endpoint, verb=verb)
File "/usr/local/lib/python2.7/dist-packages/flasgger/utils.py", line 493, in parse_docstring
swag = yaml.load(full_doc[line_feed + yaml_sep:])
File "/usr/local/lib/python2.7/dist-packages/yaml/__init__.py", line 71, in load
return loader.get_single_data()
...
...
File "/usr/local/lib/python2.7/dist-packages/yaml/parser.py", line 98, in check_event
self.current_event = self.state()
File "/usr/local/lib/python2.7/dist-packages/yaml/parser.py", line 439, in parse_block_mapping_key
"expected , but found %r" % token.id, token.start_mark)
ParserError: while parsing a block mapping
in "", line 53, column 11:
type: string
^
expected , but found ''
in "", line 54, column 31:
description: 'auto' keyword selects a pool22 i.e. a ...
```
It would be tremendously helpful for debugging documentation if something in the stacktrace was able to intercept the error and add a filename and line number (or, at least, a method and action name) to accompany the `""`, so as to easily find and fix the error.
This type of error occurs in multiple methods in `utils.py`. This particular one is closest to the `parse_docstring` method, but in the past I've had similar issues in the `extract_definitions` method, which made debugging difficult.
Contributor guide
No contributing guide indexed for this repository
Research direction
The relevant entry points are flasgger/utils.py's parse_docstring and extract_definitions, reached from the /apidocs endpoint; start by reproducing malformed YAML in a method doc and tracing where the parser error is handled. Done means the error identifies the affected method/action or source filename and line instead of only reporting and a long unparsed HTML stack trace.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- flask, python
- Domain
- api, backend, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100