Generate descriptions in OpenAPI docs using Google Cloud Endpoints Framework - google-app-engine

Question

I'm building an API using Google Cloud Endpoints Framework v2 on Python App Engine Standard.
Using Endpoints Framework means you can automatically generate OpenAPI / Swagger documentation directly from the code.
However I am unable to work out how to generate descriptions for each of the parameters (each field in a message) in the API directly from the code.
It's possible to generate a description for the entire API but not for each individual parameter.
Using Cloud Endpoints Framework Echo as an example:
"""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]
This is the accompanying swagger documentation that has been generated:
{
"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"
}
In the example above I'm looking to try and include a description for the content field in the EchoResponse and EchoRequest message types.
This could be done manually by navigating the OpenAPI specification path --> /echo/v1/echo --> parameters and adding in a description key/field there -
but can it be generated through the code?

Answer 1

Unfortunately, Endpoints Frameworks does not currently support this. The alternative you suggested of manually adding the description is the only way right now.