2017-04-15

电影订票系统后台开发（4）REST API 和 Swagger UI

电影订票系统后台开发（4）REST API 和 Swagger UI
完整项目请戳猿眼电影订票系统

Let’s go

项目开发环境

Deepin-Linux 15.4
Python 2.7.12
PyCharm
Flask

REST API

关于 REST 可以看我的另一篇博客初识REST，这里就不再赘述，这里要说的是怎样在 Flask 应用中实现 RESTful API。Flask 非常适合于开发 RESTful API，因为它具有以下特点：

使用Python进行开发，Python简洁易懂
容易上手
灵活
可以部署到不同的环境
支持RESTful请求分发

安装

Flask-RESTPlus是一个 Flask 扩展，增加了对快速构建 REST API的支持。它配置非常简单，很容易上手，而且它提供了装饰器和工具集合来描述API 并且集成了 Swagger UI 界面。Flask-RESTPlus 官方文档：

1 2	(venv) $ pip install flask-restplus # 安装 Flask-RESTPlus (venv) $ pip freeze > requiremens.txt # 更新需求文件

资源

在 REST 中，一个 URI 标识一个资源，Flask-RESTPlus 中有一个Resource类，继承这个类并实现get，post，delete，patch等函数即可处理对应的 HTTP 请求。下面以收藏模块为例：

# *-* coding: utf-8 *-*
from flask import request
from app.utils import UUID
from app.models import Favorite, Movie, db
from flask_restplus import Namespace, Resource
from flask_login import current_user, login_required
    
api = Namespace('favorite', description='收藏模块')
    
        
@api.route('/')
class FavoritesResource(Resource):
    @login_required
    def get(self):
        """获取收藏列表(需登录)"""
        return [f.__json__() for f in current_user.favorites], 200
    
    @api.doc(parser=api.parser().add_argument(
      'movieId', type=str, required=True, help='电影id', location='form')
    )
    @login_required
    def post(self):
        """收藏电影(需登录)"""
        mid = request.form.get('movieId', '')
        movie = Movie.query.get(mid)
        if movie is None:
            return {'message': '电影不存在'}, 233
        movie = current_user.favorites.filter_by(movieId=mid).first()
        if movie is not None:
            return {'message': '不能重复收藏同部电影'}, 233
    
        favorite = Favorite()
        favorite.id = UUID()
        favorite.username = current_user.id
        favorite.movieId = mid
        db.session.add(favorite)
        db.session.commit()
    
        return {'message': '收藏成功', 'id': favorite.id}, 200
    
    
@api.route('/<id>')
@api.doc(params={'id': '收藏id'})
class FavoriteResource(Resource):
    @login_required
    def delete(self, id):
        """取消收藏(需登录)"""
        favorite = current_user.favorites.filter_by(id=id).first()
        if favorite is None:
            return {'message': '您没有这个收藏'}, 233
        db.session.delete(favorite)
        db.session.commit()
        return {'message': '取消收藏成功'}, 200

创建了资源之后，只需要进行初始化即可实现 RESTful 服务。

# *-* coding: utf-8 *-*
from flask import Flask
from flask_restplus import Api
from favorite import api as ns1
    
api = Api(
    title='MonkeyEye',
    version='1.0',
    description='猿眼电影订票系统API',
    doc='/swagger/',             # Swagger UI: http://localhost:5000/swagger/
    catch_all_404s=True,
    serve_challenge_on_401=True
)
    
api.add_namespace(ns1, path='/api/favorites')
    
app = Flask(__name__)
api.init_app(app)
    
if __name__ == '__main__':
    app.run()

注意 因为我们的 API 返回的是 json 对象，因此需要给数据模型添加一个方法，返回一个 json 对象，在models.py中的数据模型的类都添加了一个__json__方法，返回前端需要的数据；`@api.route装饰器是路由监听，@login_required装饰器来自于 Flask-Login ，被装饰的函数需要用户登录，@api.doc` 是文档说明，在后面的 Swagger UI 部分就能看到它的作用了。

Swagger UI

实现了 REST API 之后，我们要怎么测试这些接口呢，有没有一种操作简便的方法呢？ Flask-RESTPlus 中就自带了 Swagger UI 界面，可以直接访问该界面查看 API 并进行测试，前面我们用`@api.doc修饰的资源和方法都会在 Swagger UI 界面呈现出来，Api(doc=’/swagger/‘)` 指定了 Swagger UI 的路径，效果如下图：

订单模块 API 界面如下：
Order Api 界面