Создайте Restful API с документацией Swagger

Спецификация OpenAPI (ранее известная как Swagger) – это языковой агностический набор спецификации, используемых для документирования API REST. Swagger Team присоединилась к SmartBear в 2015 году, и они открыли спецификацию Swagger, которая теперь называется Specification OpenAPI.

Документирование API является одним из наиболее важных шагов развития API. Этот способ документирования не только помогает другим разработчикам, но и потребителям API. Кроме того, Swagger включенные APIS также можно быстро протестировать без необходимости прохождения подробной документации.

Есть несколько Restful API -структур, которые поставляются с поддержкой документации OpenAPI в Python. В этой статье, аналогичной моему предыдущему блогу, давайте проведем пример с Flask-Restplus, который является продолжением фламбры.

Настройка проекта

Создать папку проекта – MKDIR COTES-REST-API
Настройка и активировать виртуальную среду – Настройка виртуальной среды
Установите ниже пакеты в виртуальной среде Project:

  pip install flask-restplus
  # Flask-restplus needs below version of Werkzeug
  pip install Werkzeug==0.16.0

Настройка приложения

Создайте файл с именем app.py В папке проекта и добавьте необходимый импорт, настройка приложения вместе с кодом определения модели, как показано ниже:

# necessary Imports
from flask import Flask, jsonify, request
from flask_restplus import Api, Resource, fields
from werkzeug.middleware.proxy_fix import ProxyFix


# application & documentation setup
app = Flask(__name__)
app.wsgi_app = ProxyFix(app.wsgi_app)
api = Api(app, version='1.0', title='Swagger enabled Quotes API',description='A simple Quotes API')

# namespace definition
ns = api.namespace('quotes', description='Quote CRUD operations')

# model definition - would be automatically displayed as part of API documentation
quote = api.model('quote', {
    'id': fields.Integer(readonly=True, description="Quote's unique identifier"),
    'quote_desc': fields.String(required=True, description="Quote"),
    'quote_type': fields.String(required=True, description="quote's type"),
    'author': fields.String(required=True, description="quote's author")
})

Цитаты CRUD Operations Setup

Добавить ниже класс DAO (объект доступа к данным) в класс app.py файл. Этот класс будет использоваться конечными точками API для выполнения необходимых операций CRUD. Кроме того, обратите внимание, что кавычки поддерживаются в памяти приложения как объект Python List.

# Quote class containing CRUD methods
class QuoteDAO(object):
    def __init__(self):
        self.counter = 0
        self.quotes = []

    def get(self, id):
        for q in self.quotes:
            if q['id'] == id:
                return q
        api.abort(404, "Quote {} doesn't exist".format(id))

    def create(self, data):
        q = data
        q['id'] = self.counter = self.counter + 1
        self.quotes.append(q)
        return q

    def update(self, id, data):
        q = self.get(id)
        q.update(data)
        return q

    def delete(self, id):
        q = self.get(id)
        self.quotes.remove(q)


# Initialize DAO & create sample quotes
DAO = QuoteDAO()
DAO.create({'quote_desc':'It always seem impossible until it is done.', 'quote_type': 'Motivation', 'author': 'Nelson Mandela'})
DAO.create({'quote_desc':'With the new day comes new strength and new thoughts.', 'quote_type': 'Motivation', 'author': 'Eleanor Roosevelt'})
DAO.create({'quote_desc':'The secret of getting ahead is getting started.', 'quote_type': 'Motivation', 'author': 'Mark Twain'})

Конечные точки API для операций GET и POST

Ниже класс определяет операции GET и POST для обслуживания кавычек. Ниже код также может быть добавлен к концу того же app.py файл.

# API Endpoints for listing and creating new quotes
@ns.route('/')
class QuoteList(Resource):
    '''Shows a list of all quotes, and lets you POST to add new quotes'''
    @ns.doc('list_quotes')
    @ns.marshal_list_with(quote)
    def get(self):
        '''List all quotess'''
        return DAO.quotes

    @ns.doc('create_quote')
    @ns.expect(quote)
    @ns.marshal_with(quote, code=201)
    def post(self):
        '''Create a new quote'''
        return DAO.create(api.payload), 201

Конечные точки API для других операций

Ниже класс используется для определения остальных операций CRUD. Обратите внимание на использование общих декораторов пространства имен для идентификатора цитаты, информации о ответе и маршруте.

# API Endpoints for rest of CRUD operations
@ns.route('/')
@ns.response(404, 'Quote not found')
@ns.param('id', 'The quote identifier')
class Quote(Resource):
    '''Show a single quote item and lets you delete them'''
    @ns.doc('get_quote')
    @ns.marshal_with(quote)
    def get(self, id):
        '''Fetch a quote given its identifier'''
        return DAO.get(id)

    @ns.doc('delete_quote')
    @ns.response(204, 'Quote deleted')
    def delete(self, id):
        '''Delete a quote given its identifier'''
        DAO.delete(id)
        return '', 204

    @ns.expect(quote)
    @ns.marshal_with(quote)
    def put(self, id):
        '''Update a quote given its identifier'''
        return DAO.update(id, api.payload)

Как проверить API?

Добавьте ниже код в конце файла app.py, чтобы мы могли запустить приложение, используя Python app.py командование

if __name__ == '__main__':
    app.run(debug=True)

Конечные точки API могут быть проверены в самом браузере. Попробуйте это Кнопка (показана ниже) может быть использована для получения списка кавычек.

Дальнейшее обучение

Оригинал: “https://dev.to/dev0928/build-restful-api-with-swagger-documentation-fe7”