这是《Swagger Spotlight 》系列博客的第一期，该系列旨在关注全球 Swagger 用户所做的出色工作。如果您正在使用 Swagger 工具构建项目、编写了有用的教程，或者只是想表达对 Swagger 和 API 行业的看法，我们都期待您的来稿。投稿通道已开放！
Thomas Pollet 是一名来自比利时的自由 IT 顾问
几年前，当我需要使用 Nutanix REST API 实现一个系统监控应用时，首次接触到 Swagger。我发现它是一种非常方便的调试和文档化 Web 服务的方式。后来，当被要求为另一个项目提供文档时，我又回到了 Swagger（现在的 OpenAPI），并实现了规范。
与当今大多数 Web 服务一样，该项目的 API 端点提供了 CRUD 功能：对数据库后端进行创建、读取、更新、删除操作。规范中需要描述的大部分信息已经隐式地编码在应用程序中，因此我决定不手动编写规范，而是使用可用的应用程序语义来生成它。
这是一个使用 flask-restful REST 实现和 SQLAlchemy ORM 的 Python 项目，因此其理念是从 SQLAlchemy 类声明和 flask-restful 端点定义中提取数据库对象模式，以生成 OpenAPI 规范。这非常有效，此后我改进了实现和功能，并将该项目作为一个开源 Python pip 包发布： safrs。
safrs 是所用主要技术的首字母缩写：SqlAlchemy、Flask-Restful 和 Swagger。该框架的目的是帮助 Python 开发者为 SQLAlchemy 数据库对象和关系创建自文档化的 JSON API。这些对象可以序列化为 JSON，并可以通过 JSON API 进行创建、检索、更新和删除。可选地，可以使用 JSON 公开和调用自定义资源对象方法。类和方法的描述及示例可以在代码注释中以 YAML 语法提供。描述会被解析并显示在 SwaggerUI 中。此软件包目前仅支持 v1.0 和 v2.0 版本。
示例脚本
我创建了一个小型 示例脚本 来演示该软件包的功能（示例的运行版本可在此处找到）。运行此脚本将把两个类（Users 和 Books）作为 REST 端点公开。User 类定义如下所示
class User(SAFRSBase, db.Model)
'''
description: User 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 Spotlight 系列中亮相，请点击此处提交主题！
了解更多
感谢您的阅读！正在寻找更多 API 资源？订阅 Swagger 新闻简报。每月接收包含我们最佳 API 文章、培训、教程等的电子邮件。 订阅