Question

我正在为现有服务定义OpenAPI 3.0规范，该规范涉及客户端上传文件。由于AWS Gateway中文件大小的限制，客户端无法将文件直接上传到服务。

相反，API端点将预先签名的URL返回给客户端，然后可以使用该URL将文件上传到S3。具体来说，客户必须致电：

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

我想在OpenAPI规范中清楚地记录下来。

此外，最好将第二个操作封装在根据规范生成的SDK中，也就是说，客户端SDK具有将presigned_url和文件作为参数的方法。

到目前为止，想到的两个选择是：

在/uploadurl操作上定义回调
使用静态S3 URL作为服务器/基本路径定义单独的参数化路径。

第二个选项很好，因为将在SDK中生成一个独特的方法，但是它也很尴尬，因为必须在规范中静态定义浴路径/区域，并且客户端必须解析presigned_url才能获得路径/查询参数。

回调方法没有在SDK中生成方法，并且似乎不是该回调功能的目的，即，这允许客户端以其他方式回调到服务器。

>

以下是回调的OpenAPI规范摘录：

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中处理过这种用例吗？

OpenAPI / Swagger：使用供客户端回调的回调

0 个答案: