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

[panda-byte]

A decorator approach is also used by Flask-RESTX, and I think it is superior, because it allows you to use static checking, IDE autocompletion, refactoring etc., which makes it easier to keep the docs up-to-date.

@Fatal1ty Your project sounds great, and as it is based on apispec, it should also integrate directly with marshmallow, right?

[Fatal1ty]

@Fatal1ty Your project sounds great, and as it is based on apispec, it should also integrate directly with marshmallow, right?

Not out of the box. But you can create a plugin for marshmallow models. I think there are already libraries that allow you to build json schema for marshmallow models. You can use such a library to call it in a plugin.

Or you could try reusing what's available in the MarshmallowPlugin, but I haven't tried it:

• https://github.com/marshmallow-code/apispec/blob/e4cdbadde9691051c6853837fde83e839da66878/src/apispec/ext/marshmallow/openapi.py#L241

[lafrech]

@panda-byte if you want marshmallow integration, I think you should give flask-smorest a stab.

It still lacks type hints but that would be a nice addition. Otherwise, I think it does what you want.