これは、世界中のSwaggerユーザーの素晴らしい活動に焦点を当てたブログシリーズであるSwagger Spotlight の第一弾です。Swaggerツールを使ったプロジェクトを構築している方、役立つチュートリアルをお持ちの方、またはSwaggerとAPI業界について何か言いたいことがある方は、ぜひご連絡ください。投稿は受付中です！
Thomas Polletはベルギー出身のフリーランスITコンサルタントです。
私が初めてSwaggerを知ったのは、数年前にNutanix REST APIを使ってシステム監視アプリを実装しなければならなかったときでした。ウェブサービスをデバッグし、文書化するのに非常に便利な方法だと感じました。その後、別のプロジェクトのドキュメントを提供するように依頼されたとき、私はSwagger（現在はOpenAPI）に戻り、その仕様を実装しました。
今日のほとんどのウェブサービスと同様に、このプロジェクトの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のみをサポートしています。
スクリプト例
パッケージの機能を示すために、小さなサンプルスクリプトを作成しました（この例の動作版はこちらで見つけることができます）。このスクリプトを実行すると、2つのクラス（UsersとBooks）がRESTエンドポイントとして公開されます。Userクラスの定義は次のようになります。
class User(SAFRSBase, db.Model)
'''
説明: ユーザーの説明
'''
__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データは、サンプルオブジェクトインスタンスを使用して自動的に生成されます。
開発者は、YAML形式のコメントとして追加のOpenAPI仕様の詳細を記述することもできます（例：Userクラスの「description」キーは解析され、UIのdescriptionとして使用されます）。
プロジェクトにOpenAPI仕様を使用することの利点に加えて、safrsのアプローチを使用することにはいくつかの追加の利点があります。
- OpenAPI仕様は実装と常に一貫している。
- 仕様の作成と維持にかかる手作業が少ない。
- APIはjsonapiに準拠している。
JSONウェブサービスの数は増え続けるため、現代のソフトウェアマイクロサービスアーキテクチャの複雑性を管理するには、標準化、可視性、モジュール化、自動化がますます重要になると私は信じています。そのため、Swaggerやsafrsのようなテクノロジーは大きな価値をもたらすでしょう。
ご自身で試してみたい方、またはその他の機能や例について学びたい方は、プロジェクトのGitHubページをご覧ください。
Swagger Spotlightシリーズで紹介されたい場合は、こちらをクリックしてトピックを投稿してください！
詳細はこちら
お読みいただきありがとうございます！さらに多くのAPIリソースをお探しですか？Swaggerニュースレターを購読してください。最高のAPI記事、トレーニング、チュートリアルなどが毎月メールで届きます。 購読する