合约应该放在API层中。API层是应用程序和数据源之间的中间层,它定义了数据源暴露给应用程序的接口。因此,API层应该负责定义API合约。
下面是一个Python示例,其中API层是使用Flask框架和Swagger扩展建立的:
from flask import Flask
from flask_restful import Api, Resource, reqparse
from flasgger import Swagger
app = Flask(__name__)
api = Api(app)
swagger = Swagger(app)
class HelloWorld(Resource):
def post(self):
"""
This API is used to greet users
---
parameters:
- name: greeting
in: body
type: string
required: true
description: The greeting to be displayed
responses:
200:
description: OK
"""
parser = reqparse.RequestParser()
parser.add_argument('greeting', type=str, required=True)
args = parser.parse_args()
return {'message': args['greeting']}
api.add_resource(HelloWorld, '/hello')
if __name__ == '__main__':
app.run(debug=True)
在这个例子中,我们使用Swagger标记API合同。在我们的例子中,API合同是“这个API用来问候用户”和“这个API需要参数来指定问候语”等。我们可以在Swagger UI中查看这个合约。这是一种非常方便的方式,可以帮助API开发者和使用者理解API的含义和使用方式。