Flask – очень популярная и мощная структура для создания веб -приложений. За последние годы люди использовали его для создания API REST, которые хорошо работают с отделенными, современными фронтальными приложениями.
Одна из проблем, с которой часто сталкиваются команды разработчиков, заключается в том, как облегчить разработчикам фронт-энда, было внутренним или с отдаленным сообществом, создавать клиенты, соответствующие API (веб-приложение, мобильное приложение или даже инструменты CLI …)
В дикой природе это много хороших примеров хорошо документированных API … Возьмите API Twitter: Документы великолепны, удобны для пользователя и охватывают всю доступную конечную точку советами и примерами. Любой свежий студент CS может написать небольшой инструмент Python, используя его, просто следуя документации и его примерам.
На @Ooreka мы решили следовать за Openapi (FKA Swagger 2.0) Спецификация для создания прочной документации для наших микросхрипов с помощью колбы. Давайте погрузимся.
3..2..1.. Док!
Спасибо Apispec lib, вы можете автоматически генерировать файл спецификации (обычно называемый swagger.json ) сформировать код Flask. Некоторые другие библиотеки могут сделать для вас много магии, но Apispec действительно прост в использовании и может сидеть рядом с вашим кодом, не вмешиваясь в него.
Он поддерживает Зефир и колба , позволяя вам повторно использовать свой код для создания надлежащей документации!
Давайте напишем наш сценарий поколения, например, app/scripts/openapi.py :
from apispec import APISpec
# Create spec
spec = APISpec(
title='My Awesome API',
version='1.0.42',
info=dict(
description='You know, for devs'
),
plugins=[
'apispec.ext.flask',
'apispec.ext.marshmallow'
]
)
# Reference your schemas definitions
from app.schemas import FooSchema
spec.definition('Foo', schema=FooSchema)
# ...
# Now, reference your routes.
from app.views import my_route
# We need a working context for apispec introspection.
app = create_app()
with app.test_request_context():
spec.add_path(view=my_route)
# ...
# We're good to go! Save this to a file for now.
with open('swagger.json', 'w') as f:
json.dump(spec.to_dict(), f)
Здесь мы сначала создаем новый экземпляр Apispec с некоторыми подробностями о нашем API. Затем мы добавляем наши определения (здесь мы используем зефир, чтобы определить, как наш API будет сериализовать/десериализовать данные) с Apispec.definition () Анкет Наконец, мы добавляем наши маршруты в нашу спецификацию API, используя Apispec.add_path () Анкет Apispec Проанализируйте функции вашего маршрута Docstrings, поэтому убедитесь, что вы добавили здесь несколько вещей OpenApi Yaml, как в:
@app.route('/foo/')
def my_route(gist_id):
""" Cool Foo-Bar route.
- - - # dev.to editor dislike triple hyphen, be sure to remove spaces here.
get:
summary: Foo-Bar endpoint.
description: Get a single foo with the bar ID.
parameters:
- name: bar_id
in: path
description: Bar ID
type: integer
required: true
responses:
200:
description: Foo object to be returned.
schema: FooSchema
404:
description: Foo not found.
"""
# (...)
return jsonify(foo)
В итоге вы получите действительную спецификацию JSON API. Теперь давайте посмотрим, как загрузить HTML -версию, чтобы показать ее миру!
Browserify-in все это
Действительно крутой инструмент для этого – Redoc Библиотека JavaScript от парней в Apis.guru Анкет Мы используем его, чтобы представить сгенерированную спецификацию JSON удобным образом.
Redoc – это в основном единый мини -файл JS, который вы можете включить в голый index.html файл и скажите, где ваш Swagger.json расположен. Он использует действительно аккуратный дизайн 3 столбцов: навигационная боковая панель, широкий центральный раздел с определениями конечных точек API и третьим столбцом, посвященным запросам или ответам образцов и примеров.
Cool API Documentation
Да, это было быстро. Проверьте пример реального мира Здесь Анкет
Завершая это
OpenAPI предлагает множество вариантов, которые я не освещал здесь для жесткого и упрощения. Вы можете добавить реальные конечные точки вашего сервера в DOC, добавить много подробностей о параметрах и ответах ваших маршрутов, приведите пример в ваших функциях маршрутов, которые будут проанализированы и добавлены в вашу спецификацию и т. Д.
Как последний совет, отправляйтесь в Колба cli Документация, чтобы увидеть, насколько легко вы можете зацепить свой скрипт генерации в интерфейс командной строки Flask (это даст вам несколько задировую команду, такую как flask_app = main.py колба Generate_doc ). О, и обязательно поместите это в свою процедуру непрерывной интеграции, чтобы ваша документация API была актуальной с вашим API!
Ваше здоровье!
ПРИМЕЧАНИЕ: Этот пост был первоначально опубликован Середина .
Оригинал: “https://dev.to/djiit/documenting-your-flask-powered-api-like-a-boss-9eo”