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?
Unfortunately, Endpoints Frameworks does not currently support this. The alternative you suggested of manually adding the description is the only way right now.