[python]既存のプロジェクトにswaggerを導入してみた。
今回、既存のプロジェクトにswaggerを導入してみました。
背景:
バックエンド開発完了間近にAPIの仕様書があれば今後の開発にも役立つと思ったからです。
開発側から分かれば良いのでローカル止まりでOK。
swaggerとは:
・swaggerは、RESTful APIをドキュメント化し、開発者がAPIエンドポイントにアクセスして操作するためのフレームワークです。
・具体的には、APIエンドポイントやリクエストとレスポンスのパラメータ、HTTPメソッド、レスポンスコードなどの情報を表示し、APIの説明や使用方法を記述したドキュメントを提供します。開発者は、このドキュメントを使用してAPIを理解し、APIエンドポイントにアクセスして、データの取得や更新の操作ができます。
公式ドキュメント
使い方:
1, インストール
poetry add flask_swagger_ui
2, 初期化
from flask import Flask
from flask_swagger_ui import get_swaggerui_blueprint
app = Flask(__name__)
SWAGGER_URL = '/api/docs' # URL for exposing Swagger UI (without trailing '/')
API_URL = 'http://petstore.swagger.io/v2/swagger.json' # Our API url (can of course be a local resource)
# Call factory function to create our blueprint
swaggerui_blueprint = get_swaggerui_blueprint(
SWAGGER_URL, # Swagger UI static files will be mapped to '{SWAGGER_URL}/dist/'
API_URL,
config={ # Swagger UI config overrides
'app_name': "Test application"
},
# oauth_config={ # OAuth config. See https://github.com/swagger-api/swagger-ui#oauth2-configuration .
# 'clientId': "your-client-id",
# 'clientSecret': "your-client-secret-if-required",
# 'realm': "your-realms",
# 'appName': "your-app-name",
# 'scopeSeparator': " ",
# 'additionalQueryStringParams': {'test': "hello"}
# }
)
app.register_blueprint(swaggerui_blueprint)
app.run()
# Now point your browser to localhost:5000/api/docs/
既存のプロジェクトに上記のコードを貼り付け。後からファイルを分けるが。
localhost:5000/api/docs/を立ち上げるとswaggerが表示されます。
3, configの書き方
上記(2.初期化のコード)の例では、config辞書を使用してFlask-Swagger-UIの設定を定義しています。設定には、以下のような項目があります。
"app_name": "Swagger UIのタイトル"
これらの設定をget_swaggerui_blueprint関数のconfig引数で指定します。
4, swagger-uiの表示
FlaskアプリケーションでSwagger UIを表示するには、以下のようにします。
from flask import Flask, jsonify
app = Flask(__name__)
@app.route("/swagger")
def spec():
swag = swagger(app)
swag["info"]["version"] = "1.0"
swag["info"]["title"] = "My API"
return jsonify(swag)
@app.route("/")
def home():
return "Welcome to My API!"
if __name__ == "__main__":
app.run()
上記の例では、spec()関数でSwaggerドキュメントを作成し、JSON形式で返します。home()関数では、Flaskアプリケーションのエントリーポイントを定義しています。Flask-Swagger-UIは、上記の例で/swaggerURLにSwagger UIを表示します。
5, 新規エンドポイントの追加
@app.route("/swagger")
def spec():
swag = swagger(app)
swag["info"]["version"] = "1.0"
swag["info"]["title"] = "My API"
swag['paths']['APIを書き込む{}'] = {
'get': {
'description': 'APIの説明',
'parameters': [
{
'name': 'host_name',
'description': 'パラメーター名',
'in': 'path',
'type': 'string',
'required': True
}
],
'responses': {
'200': {
'description': '説明文'
},
'404' : {
'description': '説明文'
}
}
}
}
return jsonify(swag)
6, 既存のエンドポイントの追加
swag['paths']['APIを書き込む{}'] = {
'get': {
'description': 'APIの説明',
'parameters': [
{
'name': 'host_name',
'description': 'パラメーター名',
'in': 'path',
'type': 'string',
'required': True
}
],
'responses': {
'200': {
'description': '説明文'
},
'404' : {
'description': '説明文'
}
},
'tags': ['Host Info']
}
}
上記のように、既存のエンドポイントに'tags'(下から3行目)を追加したい場合は、’tags’:[ホスト名]を追加して既存のエンドポイントに情報を追加できます。
上記のように、swagを追加し、['paths'][’指定する新規のエンドポイント’]を記述します。
'description':'APIの説明',
'patameters','response'などを記述します。
以上
Swagger-UIはAPIをブラウザで探索するためのユーザーインターフェースであり、Swagger-EditorはAPIを設計するためのツールです。両方のコンポーネントは、Swaggerの設計、文書化、およびテストを簡素化するための貴重なツールです。
参考にした使い方
Discussion