Создание API-интерфейсов Python с помощью Flask, Flask-RESTPlus и Swagger UI

Программирование

Создание API-интерфейсов Python с помощью Flask, Flask-RESTPlus и Swagger UI

Как создать интерактивную панель управления API на Python?

Что такое Swagger UI?

Пользовательский интерфейс Swagger - это инструмент для визуализации и взаимодействия с API, который автоматически создается с использованием спецификации OpenAPI. Он генерирует веб-страницу, которая помогает нам документировать различные API и взаимодействовать с ними.

Что такое Flask-RESTPlus?

Flask-RESTPlus - это расширение для Flask, которое поддерживает лучшие практики с минимальной настройкой. Он предоставляет набор декораторов и инструментов для описания API и предоставления его документации с помощью Swagger.

Установка

Вы можете установить Flask-RESTPlus с помощью pip

pip install flask-restplus

Минимальный API

from flask import Flask
from flask_restplus import Api, Resource
app = Flask(__name__)
api = Api(app)
@api.route('/hello/')
class HelloWorld(Resource):
    def get(self):
        return "Hello World"
    
if __name__ == '__main__':
    app.run()

Сохраните этот файл как app.py (или любое другое имя файла по вашему желанию), перейдите в терминал и введите python app.py (т.е. python <filename>.py), чтобы запустить программу.

Если при развертывании вы получите следующую ошибку:

from werkzeug import cached_property
ImportError: cannot import name 'cached_property'

Добавьте эту строку перед импортом flask_restplus:

import werkzeug
werkzeug.cached_property = werkzeug.utils.cached_property

Теперь запустите браузер и перейдите в http://localhost:5000, и вы должны увидеть этот экран:

Это экран пользовательского интерфейса Swagger. Он позволяет просматривать все конечные точки, а также тестировать API с помощью кнопки Попробовать.

Вы также можете просмотреть содержимое файла Swagger, посетив http://localhost:5000/swagger.json. Файл Swagger, созданный для приведенного выше кода, выглядит следующим образом:

{
    "swagger": "2.0",
    "basePath": "/",
    "paths": {
        "/hello/": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Success"
                    }
                },
                "operationId": "get_hello_world",
                "tags": [
                    "default"
                ]
            }
        }
    },
    "info": {
        "title": "API",
        "version": "1.0"
    },
    "produces": [
        "application/json"
    ],
    "consumes": [
        "application/json"
    ],
    "tags": [
        {
            "name": "default",
            "description": "Default namespace"
        }
    ],
    "responses": {
        "ParseError": {
            "description": "When a mask can't be parsed"
        },
        "MaskError": {
            "description": "When any error occurs on mask"
        }
    }
}

Получение параметров запроса

Вы можете получить параметры, переданные во время вызова API, используя reqparse

from flask import Flask
from flask_restplus import Api, Resource, reqparse
app = Flask(__name__)
api = Api(app)
parser = reqparse.RequestParser()
parser.add_argument('name', help='Specify your name')
@api.route('/hello/')
class HelloWorld(Resource):
    @api.doc(parser=parser)
    def get(self):        
        args = parser.parse_args()
        name = args['name']
        return "Hello " + name
    
if __name__ == '__main__':
    app.run()

В приведенном выше коде parser.parse_args() возвращает словарь с ключом в качестве имени аргумента и значением в качестве значения, переданного в запросе.

Это создает пользовательский интерфейс Swagger, как показано ниже:

Нажмите кнопку Попробовать, чтобы проверить API. Это приведет к следующему выводу:

Файл загружен

Чтобы использовать загрузку файлов, установите местоположение files и введите FileStorage

from flask import Flask
from flask_restplus import Api, Resource
from werkzeug.datastructures import FileStorage
app = Flask(__name__)
api = Api(app)
upload_parser = api.parser()
upload_parser.add_argument('file', 
                           location='files',
                           type=FileStorage)
@api.route('/upload/')
@api.expect(upload_parser)
class UploadDemo(Resource):
    def post(self):
        args = upload_parser.parse_args()
        file = args.get('file')
        print(file.filename)
        return "Uploaded file is " + file.filename
if __name__ == '__main__':
    app.run()

Пользовательский интерфейс Swagger, созданный для приведенного выше кода, будет следующим:

Параметры API

api = Api(app,
          version='10.5',
          title='Flask Restplus Demo',
          description='Demo to show various API parameters',
          license='MIT',
          contact='Jimit Dholakia',
          contact_url='https://in.linkedin.com/in/jimit105',
          doc = '/docs/',
          prefix='/test'
          )

version → Версия API (для документации Swagger)

title → Название API (для документации Swagger)

description → Описание API (для документации Swagger)

license → Укажите лицензию для API (для документации Swagger)

license_url → Укажите URL-адрес страницы лицензии (для документации Swagger)

contact → Укажите контактное лицо (для документации Swagger)

contact_email → Укажите адрес электронной почты контактного лица (для документации Swagger)

contact_url → Укажите URL для контактного лица (для документации Swagger)

doc → Укажите путь к документации пользовательского интерфейса Swagger. По умолчанию '/'

prefix → Укажите префикс для всех конечных точек URL

Пользовательский интерфейс Swagger, созданный для приведенного выше кода, выглядит следующим образом:

использованная литература

Https://flask-restplus.readthedocs.io/en/stable/

Ресурсы

Все фрагменты кода этой статьи доступны на моей странице GitHub.

Давайте подключимся

LinkedIn: https://www.linkedin.com/in/jimit105/
GitHub: https://github.com/jimit105
Twitter: https://twitter.com/ jimit105

Создание API-интерфейсов Python с помощью Flask, Flask-RESTPlus и Swagger UI

Программирование