我正在 Python App Engine Standard 上使用 Google Cloud Endpoints Framework v2 构建 API。
使用 Endpoints Framework 意味着您可以直接从代码中自动生成 OpenAPI / Swagger 文档。
但是，我无法直接从代码中弄清楚如何为 API 中的每个参数（消息中的每个字段）生成描述。
可以为整个 API 生成描述，但不能为每个单独的参数生成描述。
以 Cloud Endpoints Framework Echo 为例：
"""This is a sample Hello World API implemented using Google Cloud
Endpoints."""
# [START imports]
import endpoints
from protorpc import message_types
from protorpc import messages
from protorpc import remote
# [END imports]
# [START messages]
class EchoRequest(messages.Message):
content = messages.StringField(1)
class EchoResponse(messages.Message):
"""A proto Message that contains a simple string field."""
content = messages.StringField(1)
ECHO_RESOURCE = endpoints.ResourceContainer(
EchoRequest,
n=messages.IntegerField(2, default=1))
# [END messages]
# [START echo_api]
@endpoints.api(name='echo', version='v1')
class EchoApi(remote.Service):
@endpoints.method(
# This method takes a ResourceContainer defined above.
ECHO_RESOURCE,
# This method returns an Echo message.
EchoResponse,
path='echo',
http_method='POST',
name='echo')
def echo(self, request):
output_content = ' '.join([request.content] * request.n)
return EchoResponse(content=output_content)
@endpoints.method(
# This method takes a ResourceContainer defined above.
ECHO_RESOURCE,
# This method returns an Echo message.
EchoResponse,
path='echo/{n}',
http_method='POST',
name='echo_path_parameter')
def echo_path_parameter(self, request):
output_content = ' '.join([request.content] * request.n)
return EchoResponse(content=output_content)
@endpoints.method(
# This method takes a ResourceContainer defined above.
message_types.VoidMessage,
# This method returns an Echo message.
EchoResponse,
path='echo/getApiKey',
http_method='GET',
name='echo_api_key')
def echo_api_key(self, request):
return EchoResponse(content=request.get_unrecognized_field_info('key'))
@endpoints.method(
# This method takes an empty request body.
message_types.VoidMessage,
# This method returns an Echo message.
EchoResponse,
path='echo/getUserEmail',
http_method='GET',
# Require auth tokens to have the following scopes to access this API.
scopes=[endpoints.EMAIL_SCOPE],
# OAuth2 audiences allowed in incoming tokens.
audiences=['your-oauth-client-id.com'])
def get_user_email(self, request):
user = endpoints.get_current_user()
# If there's no user defined, the request was unauthenticated, so we
# raise 401 Unauthorized.
if not user:
raise endpoints.UnauthorizedException
return EchoResponse(content=user.email())
# [END echo_api]
# [START api_server]
api = endpoints.api_server([EchoApi])
# [END api_server]
这是已生成的随附 swagger 文档：
{
"basePath": "/_ah/api",
"consumes": [
"application/json"
],
"definitions": {
"MainEchoRequest": {
"properties": {
"content": {
"type": "string"
}
},
"type": "object"
},
"MainEchoResponse": {
"properties": {
"content": {
"type": "string"
}
},
"type": "object"
}
},
"host": "echo-api.endpoints.8085-dot-3333519-dot-5002-dot-devshell.appspot.com",
"info": {
"title": "echo",
"version": "v1"
},
"paths": {
"/echo/v1/echo": {
"post": {
"operationId": "EchoApi_echo",
"parameters": [
{
"in": "body",
"name": "body",
"schema": {
"$ref": "#/definitions/MainEchoRequest"
}
},
{
"default": 1,
"format": "int64",
"in": "query",
"name": "n",
"type": "string"
}
],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/MainEchoResponse"
}
}
}
}
},
"/echo/v1/echo/getApiKey": {
"get": {
"operationId": "EchoApi_echoApiKey",
"parameters": [],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/MainEchoResponse"
}
}
}
}
},
"/echo/v1/echo/getUserEmail": {
"get": {
"operationId": "EchoApi_getUserEmail",
"parameters": [],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/MainEchoResponse"
}
}
},
"security": [
{
"google_id_token-c0b0c9d9": []
}
]
}
},
"/echo/v1/echo/{n}": {
"post": {
"operationId": "EchoApi_echoPathParameter",
"parameters": [
{
"in": "body",
"name": "body",
"schema": {
"$ref": "#/definitions/MainEchoRequest"
}
},
{
"default": 1,
"format": "int64",
"in": "path",
"name": "n",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/MainEchoResponse"
}
}
}
}
}
},
"produces": [
"application/json"
],
"schemes": [
"https"
],
"securityDefinitions": {
"google_id_token": {
"authorizationUrl": "",
"flow": "implicit",
"type": "oauth2",
"x-google-issuer": "https://accounts.google.com",
"x-google-jwks_uri": "https://www.googleapis.com/oauth2/v3/certs"
},
"google_id_token-c0b0c9d9": {
"authorizationUrl": "",
"flow": "implicit",
"type": "oauth2",
"x-google-audiences": "your-oauth-client-id.com",
"x-google-issuer": "https://accounts.google.com",
"x-google-jwks_uri": "https://www.googleapis.com/oauth2/v3/certs"
}
},
"swagger": "2.0"
}
在上面的示例中，我希望尝试在EchoResponse和EchoRequest消息类型中包含内容字段的描述。
这可以通过导航 OpenAPI 规范路径 --> /echo/v1/echo --> 参数并在那里添加描述键/字段来手动完成 - 但它可以通过代码生成吗？