如何从现有的falcon api生成Open API规范？

Question

我有一个用Falcon框架编写的现有RESTful API。目前，我使用Sphinx进行API文档。我想切换到Swagger（现在称为OpenAPI）并自动生成Swagger规范。在GG上搜索了一段时间后，我发现了一个PyPi包falcon-swagger-ui。但看起来我必须手动编写规范。我想要像Sphinx这样的东西，我可以使用一些Sphinx模板编写普通的python docs字符串。现在我发现p2swagger但不知道如何设置？任何人都可以建议我该怎么办？预先感谢

Answer 1

看看falcon-apispec。

注意：falcon-apispec的文档不是最新的。函数specs.add_path()不再存在，它现在specs.path()。见例子。

以下简短示例（Falcon Quickstart Example的修改版本）应该显示它是如何工作的。

import falcon
from apispec import APISpec
from falcon_apispec import FalconPlugin
import json


class ThingsResource(object):
    def on_get(self, req, resp):
        """Handles GET requests
        ---
        description: Prints cite from Kant
        responses:
            200:
                description: Cite to be returned
        """
        resp.status = falcon.HTTP_200  # This is the default status
        resp.body = ('\nTwo things awe me most, the starry sky '
                     'above me and the moral law within me.\n'
                     '\n'
                     '    ~ Immanuel Kant\n\n')
        resp.content_type = falcon.MEDIA_TEXT


app = application = falcon.API()

things = ThingsResource()
app.add_route("/things", things)

spec = APISpec(
    title="Things APP",
    version="0.0.1",
    openapi_version='3.0',
    plugins=[FalconPlugin(app)],
)

spec.path(resource=things)

print(json.dumps(spec.to_dict))

在与（例如）gunicorn一起运行时，OpenAPI-Specs被打印出来。

函数的文档字符串必须在YAML中格式化，因此您仍然必须编写它们。对于更复杂的数据类型，建议使用marshmallow。它不是完全自动化的，但它可能会为你完成工作。

编辑：固定链接