openapi開發接口，flask-openapi3

是什么

flask-openapi3是一個基于Flask的WEB API框架，設計靈感來自于FastAPI，使用pydantic驗證數據，自動生成Swagger UI和Redoc兩種在線API文檔。

為什么

python WEB已經有很多成熟的知名框架，Flask、Django、FastAPI…，為什么還要自己開發一個呢？首先我是一個熱衷于Flask后端開發的愛好者，它是一個那么簡單、優雅、python范兒的一個輕量級框架，各種插件：REST、數據庫、表單驗證、swagger文檔…，在REST API開發過程中，我遇到了一些問題：

1. REST API插件有flask-restful和flask-restplus，其中flask-restplus支持swagger文檔生成和表單驗證，但基于Resource的API設計對REST執行的過于嚴格，顯得不是那么靈活。
2. 最知名的swagger文檔插件非flasgger莫屬了，但它很強的代碼侵入性給文檔編寫和代碼閱讀造成了一定的影響，不可否認的是在這之前我的項目中就是使用的flasgger。
3. WTForms很好的解決了表單驗證的問題，但對json數據的解析卻不是那么簡單，當然你可以重構其表單解析和驗證機制。

歸于以上原因，我決定開始flask-openapi3。

怎么用

像Flask一樣

openapi開發接口？你可以像使用Flask一樣來使用，當然你可能并不想這么做。

from flask_openapi3 import OpenAPIapp = OpenAPI(__name__)@app.route('/')
def hello_world():return 'Hello, World!'if __name__ == '__main__':app.run()

一個簡單的例子

Flask 2.x已經實現了REST API的編寫方式，像app.get、app.post、app.put、app.delete，但是它僅僅是app.route的快捷方式，參考此設計這里實現了OpenAPI，它能接收info參數——生成swagger文檔的必要信息，并給每一個API提供一個tags參數（給API分類），更進一步支持security（安全驗證）、responses（響應體驗證）等參數。
為視圖函數設計了path、query、form、body、header、cookie六個參數，來支持不同類型的參數——強大的pydantic庫為參數驗證提供了有力的支撐。

from pydantic import BaseModelfrom flask_openapi3 import OpenAPI
from flask_openapi3.models import Info, Taginfo = Info(title='book API', version='1.0.0')
app = OpenAPI(__name__, info=info)book_tag = Tag(name='book', description='圖書')class BookData(BaseModel):age: intauthor: str@app.get('/book', tags=[book_tag])
def get_book(query: BookData):"""get booksget all books"""return {"code": 0,"message": "ok","data": [{"bid": 1, "age": query.age, "author": query.author},{"bid": 2, "age": query.age, "author": query.author}]}if __name__ == '__main__':app.run(debug=True)

REST API

接下來展示一個完整的REST API例子：

from typing import Optionalfrom pydantic import BaseModel, Fieldfrom flask_openapi3 import OpenAPI
from flask_openapi3.models import Info, Tag
from flask_openapi3.models.security import HTTPBearerinfo = Info(title='book API', version='1.0.0')
securitySchemes = {"jwt": HTTPBearer(bearerFormat="JWT")}app = OpenAPI(__name__, info=info, securitySchemes=securitySchemes)book_tag = Tag(name='book', description='圖書')
security = [{"jwt": []}]class Path(BaseModel):bid: int = Field(..., description='圖書id')class BookData(BaseModel):age: Optional[int] = Field(..., ge=2, le=4, description='年齡')author: str = Field(None, min_length=2, max_length=4, description='作者')class BookDataWithID(BaseModel):bid: int = Field(..., description='圖書id')age: Optional[int] = Field(None, ge=2, le=4, description='年齡')author: str = Field(None, min_length=2, max_length=4, description='作者')class BookResponse(BaseModel):code: int = Field(0, description="狀態碼")message: str = Field("ok", description="異常信息")data: BookDataWithID@app.get('/book/<int:bid>', tags=[book_tag], responses={"200": BookResponse}, security=security)
def get_book(path: Path, query: BookData):"""獲取圖書根據圖書id獲取圖書"""return {"code": 0, "message": "ok", "data": {"bid": path.bid, "age": query.age, "author": query.author}}, 522@app.get('/book', tags=[book_tag])
def get_books(query: BookData):"""get booksget all books"""return {"code": 0,"message": "ok","data": [{"bid": 1, "age": query.age, "author": query.author},{"bid": 2, "age": query.age, "author": query.author}]}@app.post('/book', tags=[book_tag])
def create_book(body: BookData):print(body)return {"code": 0, "message": "ok"}@app.put('/book/<int:bid>', tags=[book_tag])
def update_book(path: Path, body: BookData):print(path)print(body)return {"code": 0, "message": "ok"}@app.delete('/book/<int:bid>', tags=[book_tag])
def delete_book(path: Path):print(path)return {"code": 0, "message": "ok"}if __name__ == '__main__':app.run(debug=True)

項目地址

源碼地址：點擊這里

api與openapi區別，同時也提供一個完整的項目示例