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))

在（例如）使用枪灰石运行时，会打印出OpenAPI-Specs。

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

编辑：固定链接

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

1 个答案: