目錄

01什么是 Apispec？? ? ? ? ? ? ? ? ? ?

為什么選擇 Apispec？

安裝與配置

02Apispec 的基本用法? ? ? ? ? ? ? ?

生成簡(jiǎn)單的 API 文檔

1、創(chuàng)建 Apispec 實(shí)例

2、定義 API 路由和視圖

3、添加路徑到 Apispec

集成 Flask 和 Apispec

1、安裝 Flask 和 Flask-Apispec

2、創(chuàng)建 Flask 應(yīng)用

集成 Django 和 Apispec

1、安裝 Django 和 Django-Rest-Framework

2、創(chuàng)建 Django 項(xiàng)目和應(yīng)用

3、配置 Django 項(xiàng)目

4、定義 Django 視圖

5、配置 URL

6、生成 OpenAPI 規(guī)范

03Apispec 的高級(jí)功能? ? ? ? ? ? ? ?

1. 自定義生成器

2. 支持多種框架

3. 自動(dòng)生成接口文檔

4. 與第三方工具集成

04實(shí)戰(zhàn)案例? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

1. 項(xiàng)目簡(jiǎn)介

2. 項(xiàng)目結(jié)構(gòu)

3. 安裝依賴(lài)

4. 定義模型

5. 定義視圖和序列化

6. 定義主應(yīng)用

7. 運(yùn)行應(yīng)用并查看文檔

訪問(wèn) http://localhost:5000/swagger/ 查看生成的 API 文檔。

05最佳實(shí)踐? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

06小結(jié)? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ??

---

01什么是 Apispec？? ? ? ? ? ? ? ? ? ?

Apispec 簡(jiǎn)介

Apispec 是一個(gè)用于生成?OpenAPI（Swagger）規(guī)范的 Python 庫(kù)。它能夠幫助開(kāi)發(fā)者自動(dòng)生成和維護(hù) API 文檔，提供直觀、詳細(xì)的接口說(shuō)明。通過(guò) Apispec，我們可以輕松地將 Python 函數(shù)或類(lèi)的文檔字符串轉(zhuǎn)換為符合 OpenAPI 規(guī)范的文檔，減少手動(dòng)編寫(xiě)文檔的麻煩。

為什么選擇 Apispec？

• 簡(jiǎn)潔易用：Apispec 提供了簡(jiǎn)單易用的 API，讓你可以快速上手。

• 靈活強(qiáng)大：支持多種框架（如 Flask、Django）和擴(kuò)展，讓你可以根據(jù)需要定制化文檔生成。

• 自動(dòng)化：通過(guò)自動(dòng)生成和更新文檔，減少手動(dòng)操作和維護(hù)成本。

安裝與配置

在開(kāi)始使用 Apispec 之前，我們需要先進(jìn)行安裝。你可以使用 pip 進(jìn)行安裝：

pip?install?apispec

Github 項(xiàng)目地址：

https://github.com/marshmallow-code/apispec

02Apispec 的基本用法? ? ? ? ? ? ? ?

讓我們通過(guò)幾個(gè)簡(jiǎn)單的例子來(lái)看看 Apispec 的基本用法。

生成簡(jiǎn)單的 API 文檔

1、創(chuàng)建 Apispec 實(shí)例

from?apispec?import?APISpecspec?=?APISpec(title="My?API",version="1.0.0",openapi_version="3.0.0",info=dict(description="This?is?a?sample?API"),
)

2、定義 API 路由和視圖

def?get_user(user_id):"""---get:description:?Get?a?user?by?IDparameters:-?name:?user_idin:?pathrequired:?trueschema:type:?integerresponses:200:description:?A?user?objectcontent:application/json:schema:type:?objectproperties:id:type:?integername:type:?string"""return?{"id":?user_id,?"name":?"John?Doe"}

3、添加路徑到 Apispec

spec.path(path="/users/{user_id}",operations=dict(get=dict(description="Get?a?user?by?ID",parameters=[{"name":?"user_id","in":?"path","required":?True,"schema":?{"type":?"integer"},}],responses={"200":?{"description":?"A?user?object","content":?{"application/json":?{"schema":?{"type":?"object","properties":?{"id":?{"type":?"integer"},"name":?{"type":?"string"},},}}},}},)),
)

集成 Flask 和 Apispec

1、安裝 Flask 和 Flask-Apispec

pip?install?Flask?Flask-Apispec

2、創(chuàng)建 Flask 應(yīng)用

from?flask?import?Flask,?jsonify
from?flask_apispec?import?FlaskApiSpec,?doc,?marshal_with
from?flask_apispec.views?import?MethodResource
from?marshmallow?import?Schema,?fieldsapp?=?Flask(__name__)class?UserSchema(Schema):id?=?fields.Int()name?=?fields.Str()class?UserResource(MethodResource):@doc(description='Get?a?user?by?ID',?tags=['User'])@marshal_with(UserSchema)def?get(self,?user_id):return?{"id":?user_id,?"name":?"John?Doe"}app.add_url_rule('/users/<int:user_id>',?view_func=UserResource.as_view('user_resource'))
docs?=?FlaskApiSpec(app)
docs.register(UserResource)@app.route('/swagger/')
def?swagger_ui():return?jsonify(docs.spec.to_dict())if?__name__?==?'__main__':app.run()

集成 Django 和 Apispec

1、安裝 Django 和 Django-Rest-Framework

pip?install?django?djangorestframework

2、創(chuàng)建 Django 項(xiàng)目和應(yīng)用

django-admin?startproject?myproject
cd?myproject
django-admin?startapp?myapp

3、配置 Django 項(xiàng)目

在 settings.py 中添加 rest_framework 和 apispec：

INSTALLED_APPS?=?[...'rest_framework','myapp','apispec',
]

4、定義 Django 視圖

在 myapp/views.py 中：

from?rest_framework.views?import?APIView
from?rest_framework.response?import?Response
from?rest_framework.schemas?import?AutoSchemaclass?UserView(APIView):schema?=?AutoSchema(manual_fields=[coreapi.Field('user_id',?required=True,?location='path',?schema={'type':?'integer'})])def?get(self,?request,?user_id):"""Get?a?user?by?ID.---responses:200:description:?A?user?objectcontent:application/json:schema:type:?objectproperties:id:type:?integername:type:?string"""return?Response({"id":?user_id,?"name":?"John?Doe"})

5、配置 URL

在 myapp/urls.py 中：

from?django.urls?import?path
from?.views?import?UserViewurlpatterns?=?[path('users/<int:user_id>/',?UserView.as_view(),?name='user-view'),
]

6、生成 OpenAPI 規(guī)范

在 manage.py 中：

from?apispec?import?APISpec
from?rest_framework.schemas?import?get_schema_viewspec?=?APISpec(title="My?API",version="1.0.0",openapi_version="3.0.0",
)schema_view?=?get_schema_view(title="My?API")
schema?=?schema_view.get_schema(request=None,?public=True)
spec.components.schema('User',?schema)
spec.path(path='/users/{user_id}/',?operations=schema['paths']['/users/{user_id}/'])print(spec.to_yaml())

03Apispec 的高級(jí)功能? ? ? ? ? ? ? ?

1. 自定義生成器

Apispec 提供了靈活的擴(kuò)展機(jī)制，允許你自定義生成器。你可以通過(guò)繼承和擴(kuò)展 Apispec 提供的基類(lèi)，實(shí)現(xiàn)自己的生成邏輯。

from?apispec?import?BasePluginclass?MyPlugin(BasePlugin):def?path_helper(self,?operations,?*,?resource,?**kwargs):operations.update({'get':?{'description':?'Get?a?user?by?ID','parameters':?[{'name':?'user_id',?'in':?'path',?'required':?True,?'schema':?{'type':?'integer'}}],'responses':?{'200':?{'description':?'A?user?object','content':?{'application/json':?{'schema':?{'type':?'object','properties':?{'id':?{'type':?'integer'},'name':?{'type':?'string'}}}}}}}}})spec?=?APISpec(title="My?API",version="1.0.0",openapi_version="3.0.0",plugins=[MyPlugin()],
)

2. 支持多種框架

Apispec 支持多種流行的 Python 框架，如 Flask、Django、Falcon?等。你可以根據(jù)需要選擇合適的框架和插件，快速生成 API 文檔。

3. 自動(dòng)生成接口文檔

Apispec 可以根據(jù)函數(shù)或類(lèi)的文檔字符串，自動(dòng)生成接口文檔，減少手動(dòng)編寫(xiě)文檔的工作量。

def?get_user(user_id):"""---get:description:?Get?a?user?by?IDparameters:-?name:?user_idin:?pathrequired:?trueschema:type:?integerresponses:200:description:?A?user?objectcontent:application/json:schema:type:?objectproperties:id:type:?integername:type:?string"""return?{"id":?user_id,?"name":?"John?Doe"}

4. 與第三方工具集成

Apispec 可以與許多第三方工具集成，如 Swagger UI、ReDoc?等，提供直觀的接口文檔展示和測(cè)試功能。

from?flask?import?Flask,?jsonify
from?flask_apispec?import?FlaskApiSpecapp?=?Flask(__name__)@app.route('/users/<int:user_id>',?methods=['GET'])
def?get_user(user_id):"""---get:description:?Get?a?user?by?IDparameters:-?name:?user_idin:?pathrequired:?trueschema:type:?integerresponses:200:description:?A?user?objectcontent:application/json:schema:type:?objectproperties:id:type:?integername:type:?string"""return?jsonify({"id":?user_id,?"name":?"John?Doe"})docs?=?FlaskApiSpec(app)
docs.register(get_user)if?__name__?==?'__main__':app.run()

04實(shí)戰(zhàn)案例? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

構(gòu)建一個(gè)完整的 API 文檔系統(tǒng)

1. 項(xiàng)目簡(jiǎn)介

假設(shè)我們有一個(gè)簡(jiǎn)單的用戶(hù)管理系統(tǒng)，需要為其 API 編寫(xiě)文檔。我們的 API 包括用戶(hù)的增刪改查操作，以及一些基礎(chǔ)的身份驗(yàn)證功能。

2. 項(xiàng)目結(jié)構(gòu)

user_management/
├──?app.py
├──?models.py
├──?views.py
├──?serializers.py
└──?requirements.txt

3. 安裝依賴(lài)

在 requirements.txt 中添加依賴(lài)：

Flask
Flask-RESTful
Flask-SQLAlchemy
Flask-Migrate
apispec
flask-apispec

運(yùn)行以下命令安裝依賴(lài)：

pip?install?-r?requirements.txt

4. 定義模型

在 models.py 中定義用戶(hù)模型：

from?flask_sqlalchemy?import?SQLAlchemydb?=?SQLAlchemy()class?User(db.Model):id?=?db.Column(db.Integer,?primary_key=True)name?=?db.Column(db.String(80),?nullable=False)email?=?db.Column(db.String(120),?unique=True,?nullable=False)

5. 定義視圖和序列化

在 serializers.py 中定義用戶(hù)序列化器：

from?marshmallow?import?Schema,?fieldsclass?UserSchema(Schema):id?=?fields.Int(dump_only=True)name?=?fields.Str(required=True)email?=?fields.Email(required=True)

在 views.py 中定義視圖：

from?flask?import?request
from?flask_restful?import?Resource
from?models?import?User,?db
from?serializers?import?UserSchemaclass?UserResource(Resource):def?get(self,?user_id):user?=?User.query.get_or_404(user_id)schema?=?UserSchema()return?schema.dump(user)def?post(self):schema?=?UserSchema()user?=?schema.load(request.json)db.session.add(user)db.session.commit()return?schema.dump(user),?201def?put(self,?user_id):user?=?User.query.get_or_404(user_id)schema?=?UserSchema(partial=True)updated_user?=?schema.load(request.json,?instance=user)db.session.commit()return?schema.dump(updated_user)def?delete(self,?user_id):user?=?User.query.get_or_404(user_id)db.session.delete(user)db.session.commit()return?'',?204

6. 定義主應(yīng)用

在 app.py 中：

from?flask?import?Flask
from?flask_restful?import?Api
from?flask_migrate?import?Migrate
from?models?import?db
from?views?import?UserResource
from?flask_apispec?import?FlaskApiSpec
from?flask_apispec.extension?import?FlaskApiSpecapp?=?Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI']?=?'sqlite:///users.db'
db.init_app(app)
migrate?=?Migrate(app,?db)
api?=?Api(app)api.add_resource(UserResource,?'/users/<int:user_id>')docs?=?FlaskApiSpec(app)
docs.register(UserResource)if?__name__?==?'__main__':app.run()

7. 運(yùn)行應(yīng)用并查看文檔

運(yùn)行以下命令啟動(dòng)應(yīng)用：

python?app.py

訪問(wèn) http://localhost:5000/swagger/ 查看生成的 API 文檔。

05最佳實(shí)踐? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

1. 保持文檔與代碼同步

確保文檔始終與代碼保持同步，避免出現(xiàn)文檔與實(shí)際 API 不一致的情況。你可以使用 CI/CD 工具自動(dòng)生成和部署文檔。

2. 使用注釋和裝飾器

通過(guò)使用注釋和裝飾器，可以讓文檔生成更加簡(jiǎn)潔、易讀。例如，使用 Flask-Apispec 的 @doc 裝飾器為視圖函數(shù)添加文檔信息。

3. 定義全局參數(shù)和響應(yīng)

對(duì)于常用的參數(shù)和響應(yīng)，可以在 Apispec 中定義全局參數(shù)和響應(yīng)模板，減少重復(fù)代碼。

spec.components.parameter("user_id",?"path",?schema={"type":?"integer"},?required=True)
spec.components.response("User",?{"description":?"A?user?object","content":?{"application/json":?{"schema":?{"type":?"object","properties":?{"id":?{"type":?"integer"},"name":?{"type":?"string"}}}}}
})

4. 定期審查和更新文檔

定期審查和更新文檔，確保文檔的準(zhǔn)確性和完整性?？梢酝ㄟ^(guò)設(shè)置文檔審查周期或引入文檔審查流程來(lái)實(shí)現(xiàn)。

更多功能、詳細(xì)用法可參考官方文檔：

https://apispec.readthedocs.io/en/latest

06小結(jié)? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ??

通過(guò)這篇文章，相信你已經(jīng)對(duì) Apispec 有了基本的了解和掌握。我們從基本用法到高級(jí)功能，再到實(shí)戰(zhàn)案例和最佳實(shí)踐，全面地介紹了如何使用 Apispec 生成和維護(hù) API 文檔。

希望你能將這些知識(shí)應(yīng)用到實(shí)際項(xiàng)目中，為你的 API 增加一抹亮色。