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文档跟测试界面。