OpenAPI / Swagger: использование обратного вызова, предназначенного для обратного вызова клиента - PullRequest
Новая
       20

OpenAPI / Swagger: использование обратного вызова, предназначенного для обратного вызова клиента

1 голос
/ 14 апреля 2020

Я определяю OpenAPI 3.0 spe c для существующего сервиса, который включает в себя загрузку файла клиентом. Из-за ограничений размера файла в AWS Gateway клиент не может загрузить файл напрямую в службу.

Вместо этого конечная точка API возвращает предварительно подписанный URL-адрес клиенту, который затем можно использовать для загрузки файла на S3. В частности, клиент должен позвонить:

  1. GET /uploadurl -> { "presigned_url": "string" }
  2. PUT {presigned_url} -> 200

Я хотел бы документально подтвердите это в спецификации OpenAPI c.

Кроме того, было бы идеально, если бы вторая операция была инкапсулирована в SDK, сгенерированный из spe c, то есть, чтобы у клиентского SDK был метод, который принимает presigned_url и файл в качестве параметров.

До сих пор рассматривались два варианта:

  • , определяющий обратный вызов для операции /uploadurl
  • , определяющий отдельный параметризованный путь со значением c URL-адрес S3 как сервер / базовый путь.

Второй вариант хорош, поскольку в SDK будет сгенерирован отдельный метод, но он также неудобен, так как путь / регион ванны должен быть статически определен в spe c и presigned_url должен быть проанализирован клиентом для получения параметров пути / запроса.

Метод обратного вызова не генерирует метод в SDK, и кажется, что это не то, для чего предназначена функция обратного вызова, то есть это позволяет клиенту осуществлять обратный вызов к серверу, а не наоборот. .

Ниже приведена выдержка из OpenAPI spe c для обратного вызова: 

paths:
  /uploadurl:
    get:
      tags:
        - upload
      operationId: getUploadUrl
      description: 'Returns a pre-signed URL to upload a file to the S3 bucket'
      parameters:
        - name: filename
          in: query
          description: The name of the file
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  presigned_url:
                    type: string
                    format: uri
        '422':
          description: Validation error. A filename must be provided.
        '5XX':
          description: Unexpected error.
      callbacks:
        upload:   # Event name
          '{response.body#/presigned_url}':   # The callback URL,
                                            # Refers to the passed URL
            put:
              description: >
                This callback is provided for the client to upload their dataset to 
                our S3 bucket using presigned_url provided in the response. 
                The file must be compressed as tar.gz
              requestBody:
                content:
                  application/octet-stream:
                    schema:
                      type: string
                      format: binary
              responses:   # Expected responses to the callback message
                '200':
                  description: File uploaded successfully

Если бы я мог определить полностью параметризованный путь, а не относительный к серверу, то это было бы идеально. Кто-нибудь имел дело с таким вариантом использования в Swagger?

...