Как создать спецификацию Open API из существующего сокола API? - PullRequest
Новая
       19

Как создать спецификацию Open API из существующего сокола API?

1 голос
/ 11 апреля 2019

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

1 Ответ

0 голосов
/ 30 апреля 2019

Взгляните на сокол-apispec .

Внимание: документы по сокол-apispec не актуальны.Функция specs.add_path() больше не существует, теперь она specs.path().См. Пример.

Следующий короткий пример (измененная версия Пример быстрого запуска 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 печатаются.

Строки документации функций должны быть отформатированы в YAML, поэтому вам все равно придется их писать.Для более сложных типов данных рекомендуется использовать зефир .Он не полностью автоматизирован, но, возможно, он сделает работу за вас.

РЕДАКТИРОВАТЬ: Фиксированная ссылка

...