Apispec,一个用于生成 OpenAPI(Swagger)规范的 Python 库

目录

01什么是 Apispec?                   

为什么选择 Apispec?

安装与配置

02Apispec 的基本用法               

生成简单的 API 文档

1、创建 Apispec 实例

2、定义 API 路由和视图

3、添加路径到 Apispec

集成 Flask 和 Apispec

1、安装 Flask 和 Flask-Apispec

2、创建 Flask 应用

集成 Django 和 Apispec

1、安装 Django 和 Django-Rest-Framework

2、创建 Django 项目和应用

3、配置 Django 项目

4、定义 Django 视图

5、配置 URL

6、生成 OpenAPI 规范

03Apispec 的高级功能               

1. 自定义生成器

2. 支持多种框架

3. 自动生成接口文档

4. 与第三方工具集成

04实战案例                               

1. 项目简介

2. 项目结构

3. 安装依赖

4. 定义模型

5. 定义视图和序列化

6. 定义主应用

7. 运行应用并查看文档

访问 http://localhost:5000/swagger/ 查看生成的 API 文档。

05最佳实践                               

06小结                                    



01什么是 Apispec?                   

Apispec 简介

Apispec 是一个用于生成 OpenAPI(Swagger)规范的 Python 库。它能够帮助开发者自动生成和维护 API 文档,提供直观、详细的接口说明。通过 Apispec,我们可以轻松地将 Python 函数或类的文档字符串转换为符合 OpenAPI 规范的文档,减少手动编写文档的麻烦。

为什么选择 Apispec?

  • 简洁易用:Apispec 提供了简单易用的 API,让你可以快速上手。

  • 灵活强大:支持多种框架(如 Flask、Django)和扩展,让你可以根据需要定制化文档生成。

  • 自动化:通过自动生成和更新文档,减少手动操作和维护成本。

安装与配置

在开始使用 Apispec 之前,我们需要先进行安装。你可以使用 pip 进行安装:

pip install apispec

Github 项目地址:

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

02Apispec 的基本用法               

让我们通过几个简单的例子来看看 Apispec 的基本用法。

生成简单的 API 文档

1、创建 Apispec 实例

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、创建 Flask 应用

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、创建 Django 项目和应用

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

3、配置 Django 项目

在 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 规范

在 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 的高级功能               

1. 自定义生成器

Apispec 提供了灵活的扩展机制,允许你自定义生成器。你可以通过继承和扩展 Apispec 提供的基类,实现自己的生成逻辑。

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 等。你可以根据需要选择合适的框架和插件,快速生成 API 文档。

3. 自动生成接口文档

Apispec 可以根据函数或类的文档字符串,自动生成接口文档,减少手动编写文档的工作量。

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 等,提供直观的接口文档展示和测试功能。

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实战案例                               

构建一个完整的 API 文档系统

1. 项目简介

假设我们有一个简单的用户管理系统,需要为其 API 编写文档。我们的 API 包括用户的增删改查操作,以及一些基础的身份验证功能。

2. 项目结构

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

3. 安装依赖

在 requirements.txt 中添加依赖:

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

运行以下命令安装依赖:

pip install -r requirements.txt

4. 定义模型

在 models.py 中定义用户模型:

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 中定义用户序列化器:

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. 定义主应用

在 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. 运行应用并查看文档

运行以下命令启动应用:

python app.py

访问 http://localhost:5000/swagger/ 查看生成的 API 文档。

05最佳实践                               

1. 保持文档与代码同步

确保文档始终与代码保持同步,避免出现文档与实际 API 不一致的情况。你可以使用 CI/CD 工具自动生成和部署文档。

2. 使用注释和装饰器

通过使用注释和装饰器,可以让文档生成更加简洁、易读。例如,使用 Flask-Apispec 的 @doc 装饰器为视图函数添加文档信息。

3. 定义全局参数和响应

对于常用的参数和响应,可以在 Apispec 中定义全局参数和响应模板,减少重复代码。

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. 定期审查和更新文档

定期审查和更新文档,确保文档的准确性和完整性。可以通过设置文档审查周期或引入文档审查流程来实现。

更多功能、详细用法可参考官方文档:

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

06小结                                    

通过这篇文章,相信你已经对 Apispec 有了基本的了解和掌握。我们从基本用法到高级功能,再到实战案例和最佳实践,全面地介绍了如何使用 Apispec 生成和维护 API 文档。

希望你能将这些知识应用到实际项目中,为你的 API 增加一抹亮色。

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/pingmian/42061.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

Spring Boot与Jenkins的集成

Spring Boot与Jenkins的集成 大家好&#xff0c;我是免费搭建查券返利机器人省钱赚佣金就用微赚淘客系统3.0的小编&#xff0c;也是冬天不穿秋裤&#xff0c;天冷也要风度的程序猿&#xff01; 一、引言 Jenkins作为一个开源的持续集成&#xff08;CI&#xff09;和持续交付…

计算机行业现状分析与发展前景

一、行业竞争现状 技术创新不断涌现&#xff1a;计算机行业在技术创新方面取得了长足的进步&#xff0c;如云计算、大数据、人工智能、物联网等前沿技术不断涌现&#xff0c;这些技术不仅推动了行业的快速发展&#xff0c;也为传统产业的转型升级提供了有力支撑。 行业竞争日益…

Linux开发:进程间通过Unix Domain Socket传递数据

进程间传递数据的方式有很多种,Linux还提供一种特殊的Socket用于在多进程间传递数据,就是Unix Domain Socket(UDS)。 虽然通过普通的Socket也能做到在多进程间传递数据,不过这样需要通过协议栈层的打包与拆包,未免有些浪费效率,通过UDS,数据仅仅通过一个特殊的sock文件…

熔断降级处理

什么是熔断降级 微服务雪崩效应 当微服务运行不正常&#xff0c;会导致无法正常调用微服务&#xff0c;此时会出现异常&#xff0c;如果这种异常不去处理&#xff0c;可能会导致雪崩效应 微服务的雪崩效应表现在服务与服务之间调用&#xff0c;当其中一个服务无法提供服务时…

FreeU: Free Lunch in Diffusion U-Net——【代码复现】

这篇文章发表于CVPR 2024&#xff0c;官网地址&#xff1a;ChenyangSi/FreeU: FreeU: Free Lunch in Diffusion U-Net (CVPR2024 Oral) (github.com) 一、环境准备 提前准备好python、pytorch环境 二、下载项目依赖 demo下有一个requirements.txt文件&#xff0c; pip inst…

Symfony框架:优雅构建PHP应用的强有力工具

在PHP开发的广阔天地中&#xff0c;Symfony框架以其高性能、高安全性和组件化的特点&#xff0c;成为了构建现代Web应用的热门选择。Symfony是一个基于MVC&#xff08;模型-视图-控制器&#xff09;模式的全栈框架&#xff0c;提供了一套丰富的功能和工具&#xff0c;帮助开发者…

【WEB前端2024】3D智体编程:乔布斯3D纪念馆-第55课-芝麻开门(语音 识别 控制3D纪念馆开门 和 关门)

【WEB前端2024】3D智体编程&#xff1a;乔布斯3D纪念馆-第55课-芝麻开门&#xff08;语音识别控制3D纪念馆开门和关门&#xff09; 使用dtns.network德塔世界&#xff08;开源的智体世界引擎&#xff09;&#xff0c;策划和设计《乔布斯超大型的开源3D纪念馆》的系列教程。dtn…

2.pwn的linux基础(计算机内部数据结构存储形式)

linux基础 保护层级: 分为四个ring0-ring3 一般来说就两个&#xff0c;0和3 0为内核 3为用户 权限: 用户分为多个组 文件和目录等等的权限一般都是三个&#xff0c;即可读可写可执行。 读:R&#xff0c;写:W&#xff0c;执行:X 赋予一个可执行文件执行权限就是chmod x file…

qt 如何添加子项目

首先我们正常流程创建一个项目文件&#xff1a; 这是我已经创建好的&#xff0c;请无视红线 然后找到该项目的文件夹&#xff0c;在文件夹下创建一个文件夹&#xff0c;再到创建好的文件夹下面创建一个 .pri 文件&#xff1a; &#xff08;创建文件夹&#xff09; &#xff08…

字节跳动与南开联合开源 StoryDiffusion:一键生成漫画和视频故事的神器!完全免费!

大家好&#xff0c;我是程序员X小鹿&#xff0c;前互联网大厂程序员&#xff0c;自由职业2年&#xff0c;也一名 AIGC 爱好者&#xff0c;持续分享更多前沿的「AI 工具」和「AI副业玩法」&#xff0c;欢迎一起交流~ 漫画&#xff0c;是多少人童年的回忆啊&#xff01; 记得小学…

#数据结构 链式栈

1. 概念 链式栈LinkStack 逻辑结构&#xff1a;线性结构物理结构&#xff1a;链式存储栈的特点&#xff1a;后进先出 栈具有后进先出的特点&#xff0c;我们使用链表来实现栈&#xff0c;即链式栈。那么栈顶是入栈和出栈的地方&#xff0c;单向链表有头有尾&#xff0c;那我…

Http中get与post的区别,99%的人都理解错了吧

Get和Post是HTTP请求的两种基本方法&#xff0c;要说它们的区别&#xff0c;接触过WEB开发的人都能说出一二。 最直观的区别 就是Get把参数包含在URL中&#xff0c;Post通过request body传递参数。 你可能自己写过无数个Get和Post请求&#xff0c;或者已经看过很多权威网站总…

【ARMv8/v9 GIC 系列 5.7 -- 中断路由与系统寄存器】

请阅读【ARM GICv3/v4 实战学习 】 文章目录 Interrupt routing and System register access与Group 0中断相关的寄存器与Group 1中断相关的寄存器公共寄存器Interrupt routing and System register access 在执行AArch64状态时,中断路由到异常级别(Exception Level)是由以…

容器:stack

以下是关于stack容器的一些总结&#xff1a; stack容器比较简单&#xff0c;主要包括&#xff1a; 1、构造函数&#xff1a;stack [staName] 2、添加、删除元素: push() 、pop() 3、获取栈顶元素&#xff1a;top() 4、获取栈的大小&#xff1a;size() 5、判断栈是否为空&#x…

Linux运维之管道符、重定向与环境变量

前言&#xff1a;本博客仅作记录学习使用&#xff0c;部分图片出自网络&#xff0c;如有侵犯您的权益&#xff0c;请联系删除 目录 一、输入输出重定向 二、管道命令符 三、命令行的通配符 四、常用的转义字符 五、重要的环境变量 致谢 一、输入输出重定向 输入重定向是…

javascripr如何设计弹出输入框并在网页内输出输入内容

javascript如何设计弹出输入对话框 这里就需要用到prompt语言 它的语法格式是 prompt(对话框内容&#xff09; 如何把在对话框里输入内容输出到网页里&#xff0c;需要先定义一个变量&#xff0c;用var或let都可以。 假定变量名为a&#xff0c;代码是 let aprompt(请输入…

Python统计实战:时间序列分析之一元线性回归预测和指数曲线预测

为了解决特定问题而进行的学习是提高效率的最佳途径。这种方法能够使我们专注于最相关的知识和技能&#xff0c;从而更快地掌握解决问题所需的能力。 &#xff08;以下练习题来源于《统计学—基于Python》。请在Q群455547227下载原始数据。&#xff09; 练习题 下表是某只股票…

Mysql数据库基础操作

Mysql数据库 基本概念 内核的作用&#xff1a;调用硬件资源 数据库的作用 使用数据库可以高效且条理分明地存储数据&#xff0c;使人们能够更加迅速、方便的管理数据。 数据、表、数据库 数据 描述事物的符号记录&#xff0c;包括数字&#xff0c;文字&#xff0c;图形&…

nginx的正向代理和反向代理以及tomcat

nginx的正向代理和反向代理&#xff1a; 正向代理以及缓存配置&#xff1a; 代理&#xff1a;客户端不再是直接访问服务端&#xff0c;通过代理服务器访问服务端。 正向代理&#xff1a;面向客户端&#xff0c;我们通过代理服务器的IP地址访问目标范围端。 服务端只知道代理…

开发个人Go-ChatGPT--3 服务拆分

开发个人Go-ChatGPT–3 服务拆分 个人Go-ChatGPT项目可拆分用户服务&#xff08;user&#xff09;&#xff0c;AI模型服务&#xff08;AiModel&#xff09;&#xff0c;… 每个服务都可以再分为 api 服务和 rpc 服务。api 服务对外&#xff0c;可提供给 app 调用。rpc 服务是…