Docs via Python code

[dandreevv]

The aiohttp-apispec tool uses a wrapper to create the presentation documentation.

@docs(
    summary="Test method summary",
    description="Test method description",
    responses={
        200: {
            "schema": ResponseSchema,
            "description": "Success response",
        },
    },
)
async def index(request):
    return web.json_response({"msg": "done", "data": {}})

Is there any reason why you didn't do the same? Seems to me it's simpler and gives less errors.

[kkirsche]

This is similar to FastAPI's approach as well. As FastAPI integrates it deeper into the framework, it's not a standalone decorator, instead it is part of the router definition for a route:

https://fastapi.tiangolo.com/advanced/additional-responses/?h=openapi#additional-response-with-model

[lafrech]

apispec does not do that but layers above can do it.

FastAPI is a layer above, at the same level than flask-smorest (which I maintain). flask-smorest does its best at writing doc automatically from in/out schemas, docstrings,...

[kkirsche]

@lafrech Is that saying that APISpec is unwilling to do it?

Yes, FastAPI is a layer above, but the original request is 1:1 in line with the act of documenting the responses that APISpec is already asking of users in the docstrings. As I understand it, this is asking for helpers which reduce error rates around this process, not an integration.

This adds value by being able to leverage items such as ParamSpec and other type hints to verify and/or validate that the documented responses are accurate

[Fatal1ty]

Hi, author of openapify here 👋 I couldn't put up with manually keeping the documentation up-to-date with the code, so I created a framework agnostic library with built-in JSON Schema generation. It’s now based on decorators but I have plans to develop metadata extractors to integrate more closely with web-frameworks.

[lafrech]

I wouldn't be opposed to the @doc decorator proposed in OP. Would someone be willing to give it a stab?

You may want to have a look at flask-smorest. It has a feature that parses the docstring for summary and description.

And the other elements are inferred from the marshmallow schemas passed to load arguments and dump the response.

https://flask-smorest.readthedocs.io/en/latest/quickstart.html