[Feature Request] Docstring parsing

[Arthur Goldberg]

Any interest in a feature whereby docstrings would be parsed to produce the documentation?

e.g.

    @app.get("/")
    def _(request):
        '''
        Summary of the function

        Long description

        Consumes:
          param (string) (location='query') (required)
        '''
        pass

Could be roughly equivalent to

    @app.get("/")
    @doc.consumes(doc.String(name='param'), location='query', required='true')
    @doc.summary('Summary of the function')
    @doc.description('Long description')
    def _(request):
        pass

This is something I am working on, but it might be cleaner to integrate with sanic_openapi

[Adam Hopkins]

I think that is a potentially beneficial implementation. The project needs some direction since there really is not anyone maintaining it so well right now. Is this something you would be interested in?

[Adam Hopkins]

@vltr and I were discussing possible alternatives for the future of this project. The more voices, the better.

[Arthur Goldberg]

Yes, that could be possible...
An alternate approach I was thinking about was writing some decorator that could parse stuff from the request and pass it to the function while also adding the documentation decorators, something like for example

@app.get("/")
@doc.parse_request(param=doc.String)
def _(request, param):
    pass

being equivalent to

@app.get("/")
@doc.consumes(doc.String(name='param'), location='query', required='true')
def _(request):
    if 'param' not in requests.args:
        raise InvalidUsage(...)
    param = requests.args['param']
    pass

Since the project I am working has a lot of boilerplate which looks like that, but undecided whether it would be worthwhile or not

In any case that might be more in sanic space then sanic_openapi

[Arthur Goldberg]

Quick update on this, starting work on it, should have some code that has some ideas in a week or two

Will begin with the first idea (simple docstring parsing) supporting Google and ReST styles, won't go overkill on the parsing since I don't think there is too much to worry about if something is mis-parsed, would be an easy fix if a user reported it later...

The 2nd idea I like a bit better generally since it forces the doc to reflect the implementation of the underlying code somehow, but not really sure where it would fit just yet so leaving it for now...