这是Swagger 焦点的第一个版本 – 一个专注于全球 Swagger 用户所做出色工作的博客系列。如果您正在使用 Swagger 工具构建项目，您有一个有用的教程，或者只是想说一些关于 Swagger 和 API 行业的事情，我们很乐意听取您的意见。投稿现已开放！
Thomas Pollet 是一位来自比利时的自由 IT 顾问
我第一次接触 Swagger 是几年前，当时我必须使用 nutanix REST API 实现一个系统监控应用程序。我发现它是一种非常方便的调试和记录 Web 服务的方法。后来，当被要求为另一个项目提供文档时，我再次使用了 Swagger（现在是 OpenAPI）并实现了规范。
像今天的大多数 Web 服务一样，该项目的 API 端点提供了 CRUD 功能：对数据库后端执行创建、读取、更新、删除操作。规范中需要描述的许多信息已经隐式编码到应用程序中，因此我决定使用可用的应用程序语义来生成规范，而不是手动编写规范。
这是一个使用带有 SQLAlchemy ORM 的 flask-restful REST 实现的 Python 项目，因此想法是从 SQLAlchemy 类声明和 flask-restful 端点定义中提取数据库对象模式，以生成 OpenAPI 规范。这效果很好，从那时起，我改进了实现和功能，并将该项目作为开源的 python-pip 包提供： safrs。
safrs 是主要使用技术的首字母缩写：SqlAlchemy、Flask-Restful 和 Swagger。该框架的目的是帮助 Python 开发人员为 SQLAlchemy 数据库对象和关系创建自文档化的 JSON API。这些对象可以序列化为 JSON，并且可以通过 JSON API 创建、检索、更新和删除。可选地，可以使用 JSON 公开和调用自定义资源对象方法。可以在代码注释中使用 YAML 语法提供类和方法描述以及示例。该描述将被解析并与 SwaggerUI 一起显示。此软件包目前仅支持 v 1.0 和 v 2.0。
示例脚本
我创建了一个小的示例脚本来演示该软件包的功能（可以在此处找到该示例的运行版本）。运行此脚本将公开两个类（用户和书籍）作为 REST 端点。User 类的定义如下所示
class User(SAFRSBase, db.Model)
'''
description: 用户描述
'''
__tablename__ = 'Users'
id = Column(String, primary_key=True)
name = Column(String, default='')
email = Column(String, default='')
books = db.relationship('Book', back_populates="user", lazy='dynamic')
此类将自动生成 OpenAPI 规范和符合 jsonapi 的端点
该软件还可以检测和公开数据库关系，示例中 User 类中定义的“books”关系将创建以下端点
API 期望的 JSON 数据也将通过使用示例对象实例自动生成
开发人员还可以将其他 OpenAPI 规范详细信息描述为 YAML 编码的注释（例如，User 类中的“description”键将被解析并用作 UI 中的描述）。
除了在项目中使用 OpenAPI 规范的好处外，使用 safrs 方法还有许多其他优点
- OpenAPI 规范始终与实现保持一致。
- 创建和维护规范所涉及的手动工作较少。
- API 符合 jsonapi
由于 JSON Web 服务的数量将继续增长，我认为标准化、可见性、模块化和自动化在管理现代软件微服务架构的复杂性方面越来越重要，这就是为什么像 Swagger 和 safrs 这样的技术可能会带来很多价值。
如果您有兴趣亲自尝试一下，或了解更多功能和示例，请访问该项目的github 页面。
如果您想在我们的 Swagger 焦点系列中出现，请单击此处提交主题！
了解更多
感谢您的阅读！ 正在寻找更多 API 资源？ 订阅 Swagger 新闻通讯。每月接收一封包含我们最好的 API 文章、培训、教程等内容的电子邮件。订阅