引言：
- Flask是一款流行的Python實現(xiàn)的Web開發(fā)微框架嘉冒；
- Swagger是一款Restful接口的文檔在線自動生成+功能測試功能軟件
- 當下支持 Flask 和 Swagger 的工具大概如下：
- flask-swagger
- flasgger
- flask-restplus
綜合比較了一下，flask-restplus 對框架入侵較大咆繁， flask-swagger 集成 Swagger-UI比較繁瑣讳推，故嘗試使用 flasgger。
本文簡單介紹了 flasgger 的用法玩般，以及解決的痛點和帶來的痛點银觅。
使用方法
- 安裝使用：
- 示例:
# 安裝 flasgger==0.9.5
pip install flasgger==0.9.5
- 加載 swagger
# -*- coding: utf-8 -*-
from traffic import app
from flasgger import Swagger
app.ready()
if app.g.is_dev():
# 開發(fā)環(huán)境增加 swagger 文檔,并且指定路由
swagger = Swagger(app, config={"specs_route": "/traffic/apidocs/"}, merge=True)
if __name__ == '__main__':
app.run('0.0.0.0', 3001, threaded=True)
- 在API中使用
@api.route('/member.current', perm_ids=[], methods=['GET'])
@swag_from('../../../../apidocs/member/current.yml') # 此處為文檔地址，相對路徑
def get_current_user():
"""
當前用戶昵稱及權(quán)限
:return:
"""
- 對應(yīng)的文檔說明(apidocs/member/current.yml)
tags:
- member
summary: "查詢信息接口"
description: "接口描述"
consumes:
- "application/json"
produces:
- "application/json"
responses:
200:
description: 正確返回的格式
schema:
$ref: "#/definitions/resultDto"
400:
description: Bad request
401:
description: 未登錄
403:
description: Forbidden
404:
description: Not found
500:
description: Internal Server Error
definitions:
resultDto:
type: "object"
properties:
code:
type: "string"
default: "000000"
message:
type: "string"
default: "成功"
payload:
type: "object"
properties:
role_ids:
type: "array"
items:
$ref: '#/definitions/int_format'
member_id:
type: "integer"
name:
type: "string"
origin_member_name:
type: "string"
perm_keys:
type: "array"
items:
$ref: '#/definitions/int_format'
int_format:
type: "integer"
- 功能
- API 文檔：說明了 Api 接口的基本信息坏为，請求信息究驴，返回信息
- API調(diào)試：類似 postman,自動填充參數(shù)類型和返回信息，能做基礎(chǔ)參數(shù)驗證匀伏。較之 postman 用戶體驗更佳
- 驗證參數(shù)格式類型洒忧，校驗更加嚴謹
使用 Swagger 的目的：
- 提升API的質(zhì)量，方便開發(fā)進行自測
- 前端某些框架可自動根據(jù) Swagger 生成或優(yōu)化代碼够颠，提升效率
痛點：
- 嚴謹?shù)囊?guī)范給工程師帶來不適熙侍，簡單的接口或許會花費更多的時間來維護 swagger
- 工程師需要花費學習成本
-
需要調(diào)整現(xiàn)有的工作模式
- 原有模式： 設(shè)計階段后，開發(fā)簡單快速出一份API文檔給前端，然后進行開發(fā)蛉抓。雙方交涉較少庆尘。
- 新的模式：設(shè)計階段后，開發(fā)需要花時間整理詳細的 Swagger 格式接口文檔巷送。開發(fā)需要部署 swagger 環(huán)境驶忌，交付前端，進行開發(fā)笑跛。API 文檔流程加長了
附錄：swagger yml 文件簡單規(guī)則示例(https://blog.csdn.net/u010466329/article/details/78522992)付魔，具體查閱官方文檔
- GET 接口
#接口概要
summary: 查詢所有用戶信息
#接口描述
description: 查詢出所有用戶的所有信息，用戶名飞蹂，別名
#標簽几苍，方便快速過濾出User相關(guān)的接口
tags:
- User
parameters:
#上面接口中定義了{id}，則參數(shù)列表中必須包含參數(shù)id,并且請求類型為path
- name: id
in: path
description: 要查詢的用戶的用戶名,它是唯一標識
required: true
type: string
#返回值描述晤柄，必要自動
responses:
#返回的http狀態(tài)碼
200:
description: 所有用戶信息或者用戶的集合信息
#描述返回值
schema:
#返回值格式擦剑，可選的有array,integer,string,boolean
type: array
#針對array,每個條目的格式,type定義為array．必要填寫items
items:
#引用在definitions下定義的Users
$ref: '#/definitions/User'
#執(zhí)行出錯的處理
default:
description: 操作異常,執(zhí)行失敗.返回信息描述錯誤詳情
schema:
#值類型
type: object
#定義屬性
properties:
#屬性名
message:
#類型
type: string
- POST 接口
description: 注冊一個用戶
#請求參數(shù)
parameters:
#參數(shù)key
- name: username
#傳遞方法，formData表示表單傳輸芥颈，還有query表示url拼接傳輸惠勒，path表示作為url的一部分
#body表示http頭承載參數(shù)(body只能有一個,有body不能在有其他的)
in: formData
#參數(shù)描述
description: 用戶名，不能使用已經(jīng)被注冊過的
#參數(shù)是否必要爬坑，默認false
required: true
#參數(shù)類型纠屋，可選的包括array,integer,boolean,string.使用array必須使用items
type: string
- name: password
in: formData
description: 用戶登陸密碼，加密傳輸盾计，加密存儲
required: true
type: string
- name: alias
in: formData
type: string
description: 用戶別名
#非必要字段
required: false
responses:
#返回的http狀態(tài)碼
200:
description: 通過返回值來標示執(zhí)行結(jié)果 返回true表示執(zhí)行成功
schema:
#值類型
type: object
#定義屬性
properties:
#屬性名
status:
#類型
type: boolean
#描述
description: 是否成功
#執(zhí)行出錯的處理
default:
description: 操作異常,執(zhí)行失敗.返回信息描述錯誤詳情
schema:
#值類型
type: object
#定義屬性
properties:
#屬性名
message:
#類型
type: string
- 定義model信息
definitions:
User:
#值類型
type: object
#定義屬性
properties:
#屬性名
id:
#類型
type: string
#描述
description: 用戶的唯一id
username:
type: string
description: 用戶名
alias:
type: string
description: 別名
