這是 Swagger 焦點 的第一版 – 一個部落格系列，重點介紹 Swagger 使用者在世界各地所做的出色工作。如果您正在使用 Swagger 工具建置專案、有實用的教學課程，或者只是想分享您對 Swagger 和 API 產業的看法，我們都想聽聽您的意見。歡迎投稿！
Thomas Pollet 是來自比利時的自由 IT 顧問
我第一次接觸 Swagger 是幾年前，當時我必須使用 nutanix REST API 實作一個系統監控應用程式。我發現它是除錯和記錄 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: 使用者描述
'''
__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 類別中定義的「書籍」關聯會建立下列端點
API 預期的 JSON 資料也會透過使用範例物件執行個體自動產生
開發人員也可以將其他 OpenAPI 規格詳細資料描述為 yaml 編碼的註解（例如，User 類別中的「description」鍵會被剖析並用作 UI 中的描述）。
除了使用 OpenAPI 規格對專案的好處之外，使用 safrs 方法還有許多額外優勢
- OpenAPI 規格始終與實作一致。
- 建立和維護規格所需的手動工作較少。
- API 符合 jsonapi
由於 JSON Web 服務的數量將持續增長，我相信在管理現代軟體微服務架構的複雜性方面，標準化、可見性、區隔化和自動化越來越重要，而這就是為什麼像 Swagger 和 safrs 這樣的技術可能會帶來很多價值。
如果您有興趣親自試用，或瞭解更多功能和範例，請前往專案的 github 頁面。
如果您想在我們的 Swagger 焦點系列中亮相，請按一下這裡提交主題！
瞭解更多
感謝您的閱讀！正在尋找更多 API 資源嗎？訂閱 Swagger 電子報。每月接收一封電子郵件，其中包含我們精選的最佳 API 文章、培訓、教學課程等等。訂閱