Как сгенерировать спецификацию Open API из существующего falcon api?

У меня был существующий RESTful API, написанный на платформе Falcon. В настоящее время я использую Sphinx для документации по API. Я хочу переключиться на Swagger (теперь он называется OpenAPI) и автоматически создать спецификацию Swagger. После некоторого поиска на GG я нашел пакет PyPi falcon-swagger-ui. Но похоже, что мне придется писать спецификацию вручную. Я хочу что-то вроде Sphinx, я могу написать обычную строку документов python, используя какой-нибудь шаблон Sphinx. Теперь я нашел p2swagger, но не знаю, как его настроить? Кто-нибудь может посоветовать, что мне делать? Заранее спасибо


python openapi-generator openapi swagger falconframework
person Phat Dang    schedule 11.04.2019    source источник

Ответы (1)


arrow_upward
3
arrow_downward

Взгляните на falcon-apispec.

Следующий короткий пример (измененная версия Пример быстрого запуска Falcon) должно показать, как это работает.

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. Он не полностью автоматизирован, но, возможно, он сделает эту работу за вас.

РЕДАКТИРОВАТЬ: исправлена ​​​​ссылка

person Dominik Rimpf    schedule 30.04.2019