python+Flask+swagger的用法

1. 说明

 先来看一个应用场景：
 我写了一段功能性的程序（多是Java的，也多是Python的），供他人调用（调我程序多是其它编程语言，或者直接运行，若是调用者对我使用的工具不熟悉，直接调用可能很麻烦），这个程序须要传入多个参数，须要结构化的输出，我以什么方式提供给比较好呢？
 咱们可能会选择BS的结构，创建一个Web-Server，而后把功能性的程序放在Web-Server上并向外暴露接口，其它程序用Http协议调用该接口，以POST或GET的方式转入参数，而后获得返回结果。
 因而咱们就须要定义一些交互协议，写接口描述文档，在调用出错时，联调是哪一端的问题，总之，沟通成本很高。
 Swagger能够很好地解这一问题，一方面，它能按规范自动生成接口文档（以网页形式提供），这样编写API和编写文档同时完成，几乎不用考虑文本和 代码版本不一样步的问题；另外一方面，它能提供测试界面，咱们只须要在网页上填写相应的参数，点击调用（网页由swagger生成），就能够轻松调用接口，使 得服务端的开发者，不使用客户端，就能够完整地调试代码。javascript

2. Python & Flask & Swagger实现

(1) 工具介绍php

i. Python
 在这里选择介绍Python+Swagger，由于Python真的很是简单，不须要关心太多的代码，库，复杂的环境，只要关注流程自己便可。
另外，我这里的开发环境是python 2.7。html

ii. Flask
 Flask是Python的Web框架，Python的Web框架还有Django，Tornado，Bottle等等，Flask功能虽然不及Django和Tornado强大，但它是个轻量级的工具，三方开源组件也比较丰富。java

iii. Swagger
 支持Python+Flask的Swagger库很多，有flask-swag，flask-swagger，flasgger，本例中选用的是flasgger，它的软件包中包括了Swagger-UI，除了安装工具包，几乎不须要配置其它环境。node

iv. Nodejs与npm
 Nodejs是服务器后端的JavaScript的工具。
 Npm是一个JavaScript的包管理程序，它就像python中的pip，用于下载和管理三方工具。
 Swagger主要是用javascript实现的，所以依赖node工具集。python

(2) 安装Node工具集linux

 虽然node能用apt-get方式安装，但最好下载使用最新版本的node，版本太旧可能遇到各类问题。
 我下载的是http://nodejs.cn/download/ 中64位的linux版本，这里面也包括NPM工具，不用另外安装。解压以后，将其中的bin, lib等目录复制到/usr/local/的对应目录下便可使用。

(3) 安装Python的三方工具包github

$ sudo pip install flask
$ sudo pip install flasgger

(4) 编写test.py程序n

#coding:utf8

import sys
import random
reload(sys)
sys.setdefaultencoding('utf8')
from flask import Flask,Blueprint,render_template,request,redirect,jsonify
from flasgger import Swagger,swag_from

app = Flask(__name__)
Swagger(app)

@app.route('/api/<string:language>/', methods=['GET'])
def index(language):
    """
    This is the language awesomeness API
    Call this api passing a language name and get back its features
    ---
    tags:
      - Awesomeness Language API
    parameters:
      - name: language
        in: path
        type: string
        required: true
        description: The language name
      - name: size
        in: query
        type: integer
        description: size of awesomeness
    responses:
      500:
        description: Error The language is not awesome!
      200:
        description: A language with its awesomeness
        schema:
          id: awesome
          properties:
            language:
              type: string
              description: The language name
              default: Lua
            features:
              type: array
              description: The awesomeness list
              items:
                type: string
              default: ["perfect", "simple", "lovely"]

    """

    language = language.lower().strip()
    features = [
        "awesome", "great", "dynamic", 
        "simple", "powerful", "amazing", 
        "perfect", "beauty", "lovely"
    ]
    size = int(request.args.get('size', 1))
    if language in ['php', 'vb', 'visualbasic', 'actionscript']:
        return "An error occurred, invalid language for awesomeness", 500
    return jsonify(
        language=language,
        features=random.sample(features, size)
    )

app.run(debug=True)

(5) 运行test.py程序

此时，用浏览器访问：http://localhost:5000/apidocs/，就能够看到Swagger界面了，程序中双引号内是一个很是简单的接口描述，咱们能够把它写程序中，或者用@swag_from('index.yml')的方式，将描述文件yml引入程序。
在该界面上点“try it out”，按钮就能够在网页上测试该接口。

3. 其它工具和方法

 在网上看到通常安装swagger方法，是从git下载swagger-edit，swagger-ui：

$ git clone https://github.com/swagger-api/swagger-editor
$ git clone https://github.com/swagger-api/swagger-ui

 而后用工具http-server经过调用其目录中的index.html提供Web界面，其中的接口在yml文件中定义，yml接口通常是在编写API时程序时，经过引入swagger相关库，按照规则，自动生成的，手动编写yml文件的比较少。步骤也相对比较复杂。

4. 参考

(1) Flasgger使用心得

https://changsiyuan.github.io/2017/05/20/2017-5-20-flasgger/