Python腳本輕鬆上手Swagger，快速構建API文檔與測試

簡介

Swagger是一個富強的API文檔跟測試東西，可能幫助開辟者輕鬆地創建跟保護API文檔，並供給一個互動式的API測試界面。本文將介紹怎樣利用Python跟Flasgger庫來疾速構建API文檔跟測試。

籌備任務

1. 安裝Flask跟Flasgger庫：

pip install Flask Flasgger

1. 創建一個Python文件，比方app.py。

創建Flask利用

起首，導入所需的庫並創建一個Flask利用：

from flask import Flask
from flasgger import Swagger

app = Flask(__name__)
swagger = Swagger(app)

定義API端點

接上去，定義API端點。利用Flasgger供給的裝潢器來主動生成API文檔：

@app.route('/api/user', methods=['GET'])
@swagger.doc({
    'tags': ['user'],
    'description': 'Get user information',
    'parameters': [
        {
            'name': 'user_id',
            'in': 'path',
            'type': 'integer',
            'required': True,
            'description': 'User ID'
        }
    ],
    'responses': {
        '200': {
            'description': 'User information',
            'schema': {
                'type': 'object',
                'properties': {
                    'id': {
                        'type': 'integer',
                        'example': 1
                    },
                    'name': {
                        'type': 'string',
                        'example': 'John Doe'
                    },
                    'email': {
                        'type': 'string',
                        'example': 'john.doe@example.com'
                    }
                }
            }
        }
    }
})
def get_user(user_id):
    # 這裡可能增加獲取用戶信息的邏輯
    return {
        'id': user_id,
        'name': 'John Doe',
        'email': 'john.doe@example.com'
    }

啟動利用

在app.py文件中增加以下代碼來啟動利用：

if __name__ == '__main__':
    app.run(debug=True)

拜訪API文檔

在瀏覽器中拜訪http://localhost:5000/apidocs/，即可看到主動生成的API文檔。

測試API端點

在Swagger UI中，可能直接測試API端點。在左側菜單中抉擇響應的API端點，然後點擊「Try it out」按鈕停止測試。

總結

利用Python跟Flasgger庫可能輕鬆地構建API文檔跟測試。經由過程Flasgger的裝潢器，可能便利地增加API端點的描述信息，並主動生成文檔。Swagger UI供給了一個互動式的測試界面，便利開辟者測試API端點。

代碼示例

以下是完全的app.py文件代碼：

from flask import Flask
from flasgger import Swagger

app = Flask(__name__)
swagger = Swagger(app)

@app.route('/api/user', methods=['GET'])
@swagger.doc({
    'tags': ['user'],
    'description': 'Get user information',
    'parameters': [
        {
            'name': 'user_id',
            'in': 'path',
            'type': 'integer',
            'required': True,
            'description': 'User ID'
        }
    ],
    'responses': {
        '200': {
            'description': 'User information',
            'schema': {
                'type': 'object',
                'properties': {
                    'id': {
                        'type': 'integer',
                        'example': 1
                    },
                    'name': {
                        'type': 'string',
                        'example': 'John Doe'
                    },
                    'email': {
                        'type': 'string',
                        'example': 'john.doe@example.com'
                    }
                }
            }
        }
    }
})
def get_user(user_id):
    return {
        'id': user_id,
        'name': 'John Doe',
        'email': 'john.doe@example.com'
    }

if __name__ == '__main__':
    app.run(debug=True)

運轉app.py文件，然後在瀏覽器中拜訪http://localhost:5000/apidocs/，即可看到API文檔跟測試界面。