flasgger / flasgger/flasgger

Improve Error Message Specificity for Incorrect YAML

Open
#225 0 comments 1 reaction 0 assignees View on GitHub
hacktoberfest
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:

![flasgger-bad-1](https://user-images.githubusercontent.com/12699114/43736262-fa184530-998a-11e8-9629-9231bff6b6ec.png)

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.