search

alysivji / falcon-apispec

apispec plugin that generates OpenAPI specification (aka Swagger Docs) for Falcon web applications.
MIT License
44 stars 31 forks source link

Autogenerate method respoces. #24

Open jitka opened 4 years ago

jitka commented 4 years ago

Hi,

I am using this library and I am happy whit it, but I would like to propose an improvement.

My doc strings become quite long and see two ways to shorten them.

1) I use a lot of parameters across many functions. I do not like copy-pasting:

      - in: query
        name: deleted
        description: Filter active or deleted authors
        required: false
        type: boolean

Is there any way how to put this information to variable and use it in that docstring?

2) Responses could be read in code. I would like to search source code of function for falcon.HTTP_404 and similar and add it too responses read form function docstring. This probably don't cover all cases since this error could be renamed but I believe this could help. Would you accept a pull request with it?

jitka commented 4 years ago

And I see third option how to minimalize copy-pasting: If path parameters would be taken as a sum of things in docstring and things in a docstring of the parent object.

alysivji commented 4 years ago

I like the idea of autogenerating documentation.

Currently we grab docstrings from Falcon app and pass them to apispec. For autogeneration, we would have to modify (or generate) that docstring before it gets sent to apispec.

This is definitely possible, but it's beyond the scope of what I am comfortable supporting with this library. I don't use Falcon at work anymore. I don't mind adding small features, but this would be pretty complex.

I am definitely okay with folks forking this project and going down another route. Would also be open to transferring the package name on PyPI if that's how the users want to proceed.

If I was still using Falcon at work, I would create a decorator-based generator similar to what flask-apispec and drf-yasg do