使用在OpenAPI文档中生成描述

Question

我在标准上使用v2构建一个API。

使用终结点框架意味着您可以直接从代码生成OpenAPI / Swagger文档。

但是，我无法从代码中直接为API中的每个参数(消息中的每个字段)生成描述。

可以为整个API生成描述，但不能为每个参数生成描述。

以云端点框架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 ->参数并在其中添加一个描述键/字段-但是它能通过代码生成吗？

Answer 1

不幸的是，端点框架目前不支持这一点。您建议的手动添加描述的替代方法是目前唯一的方法。