Autogenerating swagger from directory with separate yaml files

[SomeAkk]

In aiohttp-swagger (another library, not aiohttps-swagger3) we can use decorator to decorate route function with yaml file which contain all swagger for that route. This feature help not to write a lot of code in docstrings and working like in example:

@swagger('./swagger/v1/account/create_accounts.yaml')
async def create_accounts(request):
    """Awesome function which linked to /api/v1/account method which create account
    """
    engine = request.app['db']
    # code ...

create_accounts.yaml - yaml which contain part of swagger only for route /api/v1/account, because its with examples, requests it is over 150 lines at all. Of course add 150 lines to docstring near create_accounts(request) - not a way to solve that problem.

Because aiohttps-swagger not maintained at now, i can't talk with any maintainers and can't ask anybody to improve that mechanism.

In my world it must work such that:

1. We make directory in project like my_project/swagger (in that directory we well save all yamls for each route)
2. In each yaml in operationId we set full path to function (my_project.my_module1.my_module2.create_accounts)
3. set path to directory in Swagger constructor
4. library create swagger by using directory path + operationId (by looking in all yamls in my_project/swagger in operationId field and juxtapose it to route method field in aiohttp)

Is will be okay to create pull request to that project, aiohttp-swagger3, with functional such i wrote before?

[hh-h]

Why don't you use spec file? see example https://github.com/hh-h/aiohttp-swagger3/tree/master/examples/file_spec

[hh-h]

Sure, you have two routes, GET and POST with a huge swagger schema with examples, etc. You don't want to store it like this

def get():
   """
   docstring
   ---
   huge swagger schema for GET
   """
   ...

def post():
   """
   docstring
   ---
   huge swagger schema for POST
   """
   ...

So you can put these huge schemas in YAML files and link them to a route like this

@swagger_docs("../swagger/get.yaml")
def get():
   """
   docstring
   """
   ...

@swagger_docs("../swagger/post.yaml")
def post():
   """
   docstring
   """
   ...

Note that you don't need to add/register any folders, just specify the relative path to the YAML file

[SomeAkk]

ah, ok - i misunderstood your phrase and thing that you wand to do mixed variant:

@swagger_docs("../swagger/post.yaml")
def post():
   """
   docstring
   ---
   awesome swagger additional data for post.yaml which will be added to post.yaml
   """
   ...

What you can do - is pretty good design from aiohttp-swagger, but not perfect at all. It's not feels while you have not any another decorators for post() or get() - thats why i start that discussion: we had another decorators and now 2-3 decorators one-by-one looks dirty. Ideal for me, also for my сolleagues too, is like that:

# ../swagger/post.yaml - also exist and post() linked to it with some sort of magic
# if no any yaml for that function - nothing is linked, no more magic
def post():
   """
   docstring
   """
   ...

The idea was in that: write magic byself only for our code or write it for library.

[hh-h]

Sorry, but I don't want to mess with magic via operationId.

Explicit is better than implicit.

https://www.python.org/dev/peps/pep-0020/

The decorator can be added, so the user can choose: either to use the docstring or attach the decorator to the handler.

[SomeAkk]

No problem, if so - will be waiting decorators.

[hh-h]

released a new version, check the example https://github.com/hh-h/aiohttp-swagger3/tree/master/examples/docs_decorator_and_docstrings