1. 說明

?先來看一個應(yīng)用場景：
?我寫了一段功能性的程序（可能是Java的，也可能是Python的），供他人調(diào)用（調(diào)我程序可能是其它編程語言，或者直接運行，如果調(diào)用者對我使用的工具不熟悉，直接調(diào)用可能很麻煩），這個程序需要傳入多個參數(shù)，需要結(jié)構(gòu)化的輸出，我以什么方式提供給比較好呢？
?我們可能會選擇BS的結(jié)構(gòu)，建立一個Web-Server，然后把功能性的程序放在Web-Server上并向外暴露接口，其它程序用Http協(xié)議調(diào)用該接口，以POST或GET的方式轉(zhuǎn)入?yún)?shù)，然后得到返回結(jié)果。
?于是我們就需要定義一些交互協(xié)議，寫接口描述文檔，在調(diào)用出錯時，聯(lián)調(diào)是哪一端的問題，總之，溝通成本很高。
?Swagger可以很好地解這一問題，一方面，它能按規(guī)范自動生成接口文檔（以網(wǎng)頁形式提供），這樣編寫API和編寫文檔同時完成，幾乎不用考慮文本和代碼版本不同步的問題；另一方面，它能提供測試界面，我們只需要在網(wǎng)頁上填寫相應(yīng)的參數(shù)，點擊調(diào)用（網(wǎng)頁由swagger生成），就可以輕松調(diào)用接口，使得服務(wù)端的開發(fā)者，不使用客戶端，就可以完整地調(diào)試代碼。

2. Python & Flask & Swagger實現(xiàn)

(1) 工具介紹

i. Python
?在這里選擇介紹Python+Swagger，因為Python真的非常簡單，不需要關(guān)心太多的代碼，庫，復(fù)雜的環(huán)境，只要關(guān)注流程本身即可。
另外，我這里的開發(fā)環(huán)境是python 2.7。

ii. Flask
?Flask是Python的Web框架，Python的Web框架還有Django，Tornado，Bottle等等，F(xiàn)lask功能雖然不及Django和Tornado強大，但它是個輕量級的工具，三方開源組件也比較豐富。

iii. Swagger
?支持Python+Flask的Swagger庫不少，有flask-swag，flask-swagger，flasgger，本例中選用的是flasgger，它的軟件包中包括了Swagger-UI，除了安裝工具包，幾乎不需要配置其它環(huán)境。

iv. Nodejs與npm
?Nodejs是服務(wù)器后端的JavaScript的工具。
?Npm是一個JavaScript的包管理程序，它就像python中的pip，用于下載和管理三方工具。
?Swagger主要是用javascript實現(xiàn)的，因此依賴node工具集。

(2) 安裝Node工具集

?雖然node能用apt-get方式安裝，但最好下載使用最新版本的node，版本太舊可能遇到各種問題。
?我下載的是http://nodejs.cn/download/ 中64位的linux版本，這里面也包括NPM工具，不用另外安裝。解壓之后，將其中的bin, lib等目錄復(fù)制到/usr/local/的對應(yīng)目錄下即可使用。

(3) 安裝Python的三方工具包

$ sudo pip install flask
$ sudo pip install flasgger

(4) 編寫test.py程序

#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程序

$ python test.py

?此時，用瀏覽器訪問：http://localhost:5000/apidocs/，就可以看到Swagger界面了，程序中雙引號內(nèi)是一個非常簡單的接口描述，我們可以把它寫程序中，或者用@swag_from('index.yml')的方式，將描述文件yml引入程序。
在該界面上點“try it out”，按鈕就可以在網(wǎng)頁上測試該接口。

3. 其它工具和方法

?在網(wǎng)上看到一般安裝swagger方法，是從git下載swagger-edit，swagger-ui：

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

?然后用工具h(yuǎn)ttp-server通過調(diào)用其目錄中的index.html提供Web界面，其中的接口在yml文件中定義，yml接口一般是在編寫API時程序時，通過引入swagger相關(guān)庫，按照規(guī)則，自動生成的，手動編寫yml文件的比較少。步驟也相對比較復(fù)雜。

4. 參考

(1) Flasgger使用心得

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