导入标准OAS定义

导入标准OAS格式的API定义

主要包括如下过程：

• 选择目标分组和全局信息。

• 录入OAS 2.0格式的API定义，或OAS 3.0格式的API定义

• 进行预检并根据检查结果进行调整。

• 执行导入。

导入完成后，会在目标分组中创建对应的API，后续还需进行“发布到目标环境”、“接口调试”等过程，这些过程详见API 调试。

1. 登录API网关控制台。

2. 在控制台左侧菜单中，选择开放API > API列表。

3. 在API列表页面中，单击右侧导入Swagger按钮。

4. 在弹出框中选择导入方式，选择标准OAS导入，进入配置页面。

   1. 基本信息。主要是选择导入的目标分组。

      参数	描述
      导入的分组	导入的目标分组。 重要 如果使用OAS 2.0导入时，目标API分组的basepath（例如创建分组）需要与OAS定义中的basepath（OAS的basePath定义）保持一致，否则将无法导入。
      是否覆盖	当选择覆盖时：如果遇到请求路径和HTTP请求冲突时，自动覆盖（更新）原有API； 当不选择覆盖时：如果遇到请求路径和HTTP请求冲突时，返回错误提示API已经存在。
      API定义版本	当前支持OAS 2.0和OAS 3.0的导入方式。

   2. （可选）全局配置。设置能够API的通用信息。

      参数	描述
      后端服务	默认的后端类型都为Mock类型，可以指定API网关上创建的HTTP、VPC、混合、服务发现类型的后端服务（使用后端服务提高管理效率）。
      入参请求模式	默认的方式为参数透传，可以选择参数透传/参数映射。 说明 如果入参请求模式为透传模式，API定义中的参数定义只会录入path参数，query，header，formdata，body等参数将会忽略。
      API认证方式	默认的方式为阿里云APP，可以选择阿里云APP/无认证。 说明 后端服务，参数透传，API认证为全局配置，一经配置将对所有API生效；但是如果OAS定义中使用了API网关支持的扩展字段来声明这些配置，优先级顺序为：OAS中API定义，OAS中全局定义，选填的全局配置。扩展字段将在后文进行说明。 AppCode认证：安全认证模式为APP认证时，AppCode认证默认为禁止AppCode认证；签名算法：默认为HMAC_SHA256。

   3. API定义。确定计划导入的OAS定义内容，支持文本和OSS链接两种方式：

      重要

      当前两种方式都最多支持同时导入100个API定义。

      1. 文本。支持填入yaml或json格式的API定义内容。通过文本填入的定义内容，最大支持256KB。

      2. OSS链接。支持填写一个OSS文件地址，文件类型需为json或者yaml，且OSS地址需要允许匿名访问。此方式下不限制文件大小。

5. 其他默认信息。导入API时需要的信息，但并未在配置页面中提供设置，默认值如下：

   默认信息	描述
   防止重放攻击	未开启。
   禁止公网访问	未开启。
   允许上架云市场	未开启。

6. 单击预检按钮，系统将会对计划导入的内容进行检查，检测出OAS定义中的API定义和模型定义，以及告警和错误信息。

   说明

   警告信息：警告信息可以在导入的时候选择忽略，但是存在警告信息的API定义部分在导入的过程中会被忽略；

   错误信息：错误信息不可忽略，错误信息必须进行订正，不订正进行导入会直接抛出异常。

7. 预检过程中没有错误信息和警告信息（或者忽略警告信息之后），可执行导入。单击导入Swagger按钮，系统真正开始导入API，导入API需要一定时间，导入过程请勿关闭浏览器。

8. 待系统执行完毕后，可查看到API导入结果。

标准OAS2.0格式与API网关的对应

1. Swagger Object：

   1. BasePath：对应分组的BasePath，导入时需要认证；

   2. Schemes：对应API定义中请求部分支持的协议；

2. Path Item Object：

   1. Path：对应API定义中请求部分的请求path；

   2. Method：对应API定义中请求部分的Method，支持GET，POST，PUT，HEAD，DELETE，PATCH，OPTIONS；

3. Operation Object：

   1. Summary：对应API定义的描述；

   2. OperationId：对应API定义的API名称，如果存在扩展字段“x-aliyun-apigateway-api-name”则使用扩展字段中的内容作为API的名称；

   3. Schemes：对应API定义中请求部分支持的协议，优先级高于Swagger Object中的定义；

4. Parameter Object：

   1. Name：对应API定义中请求部分的参数名称；

   2. In：对应API定义中请求部分的参数位置，支持path，query，head，formdata；

   3. Description：对应API定义中请求部分的参数描述；

   4. Required：对应API定义中请求部分的参数是否必填；

   5. Type：对应API定义中请求部分的参数类型；

      1. query，path，head类型的参数支持string，number，integer，boolean，array；

      2. formdata类型的参数支持string，number，integer，boolean，array和file；

   6. Format：对应API定义中请求部分的参数类型，如果Format存在，Format定义优先级高于Type类型。

      OAS参数类型与API网关参数类型的映射关系：

      OAS定义参数类型	API网关参数定义类型
      String	String
      Boolean	Boolean
      Array	Array
      Int32	Int
      Int64	Long
      Double	Double
      Float	Float
      File	File

      说明

      1. 如果API定义的入参请求模式为透传模式，API定义中的参数定义只会录入path参数，query，header，formdata，body等参数将会忽略；

      2. 如果API定义的入参请求模式为透传模式，没有使用API网关扩展字段的情况下，API定义中请求部分和后端服务部分的请求方法，请求路径，参数定义保持一致；

      3. 对于body位置的参数，如果参数类型为引用类型，不会在API网关的API定义中体现，只会在生成文档的时候体现。

5. Response Object：

   1. HTTP Status Code：对应API定义中定义返回结果中错误码定义中的错误码；

   2. Description：对应API定义中定义返回结果中错误码定义中的描述；

   3. Schema：对应API定义中定义返回结果中错误码定义中的模型；

6. Definitions Object：

   该项定义中的对象，在导入的过程中，API网关会将模型创建在分组下，查看模型定义可以通过分组管理列表下，对应分组的操作栏中的模型管理查看。

7. OAS 2.0格式定义举例，如下为PetStore的接口定义，帮助您快速了解本功能。

   swagger: "2.0"
   info:
     version: "1.0.0"
     title: "Swagger Petstore 2.0"
   basePath: "/"
   schemes:
   - "https"
   - "http"
   paths:
     /pet/findByStatus:
       get:
         tags:
         - "pet"
         summary: "Finds Pets by status"
         operationId: "findPetsByStatus"
         parameters:
         - name: "status"
           in: "query"
           required: true
           type: "array"
           items:
             type: "string"
             enum:
             - "available"
             - "pending"
             - "sold"
             default: "available"
           collectionFormat: "multi"
         responses:
           "200":
             description: "successful operation"
             schema:
               type: "array"
               items:
                 $ref: "#/definitions/Pet"
           "400":
             description: "Invalid status value"
   definitions:
     Category:
       type: "object"
       properties:
         id:
           type: "integer"
           format: "int64"
         name:
           type: "string"
     Tag:
       type: "object"
       properties:
         id:
           type: "integer"
           format: "int64"
         name:
           type: "string"
     Pet:
       type: "object"
       required:
       - "name"
       - "photoUrls"
       properties:
         id:
           type: "integer"
           format: "int64"
         category:
           $ref: "#/definitions/Category"
         name:
           type: "string"
           example: "doggie"
         photoUrls:
           type: "array"
           items:
             type: "string"
         tags:
           type: "array"
           items:
             $ref: "#/definitions/Tag"
         status:
           type: "string"
           description: "pet status in the store"
           enum:
           - "available"
           - "pending"
           - "sold"

标准OAS3.0格式与API网关的对应

1. Path Item Object

   1. Path：对应API定义中请求部分的请求path；

   2. Method：对应API定义中请求部分的Method，支持GET，POST，PUT，HEAD，DELETE，PATCH，OPTIONS；

2. Operation Object

   1. Summary：对应API定义的描述；

   2. OperationId：对应API定义的API名称，如果存在扩展字段“x-aliyun-apigateway-api-name”则使用扩展字段中的内容作为API的名称；

3. Parameter Object

   1. Name：对应API定义中请求部分的参数名称；

   2. In：对应API定义中请求部分的参数位置，支持path，query，head，formdata；

   3. Required：对应API定义中请求部分的参数是否必填；

4. Schema Object：

   1. Description：对应API定义中请求部分的参数描述；

   2. Type：对应API定义中请求部分的参数类型；

      1. query，path，head类型的参数支持string，number，integer，boolean，array；

      2. formdata类型的参数支持string，number，integer，boolean，array和file；

   3. Format：对应API定义中请求部分的参数类型，如果Format存在，Format定义优先级高于Type类型。

5. Request Body Object

   1. Content：

      1. application/x-www-form-urlencoded：对应API定义中的formdata类型的参数；

      2. application/json：该项定义中的对象，在导入的过程中，API网关会将模型创建在分组下，查看模型定义可以通过分组管理列表下，对应分组的操作栏中的模型管理查看。

6. Responses Object

   1. HTTP Status Code：对应API定义中定义返回结果中错误码定义中的错误码；

   2. Description：对应API定义中定义返回结果中错误码定义中的描述；

   3. Content：对应API定义中定义返回结果中错误码定义中的模型；

7. OAS 3.0格式定义举例，如下为PetStore的接口定义，帮助您快速了解本功能。

   openapi: 3.0.0
   info:
     title: Swagger Petstore - OpenAPI 3.0
     version: 1.0.0
   paths:
     /pet:
       put:
         tags:
           - pet
         summary: Update an existing pet
         description: Update an existing pet by Id
         operationId: updatePet
         requestBody:
           description: Update an existent pet in the store
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Pet'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Pet'
           required: true
         responses:
           '200':
             description: Successful operation
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/Pet'          
           '400':
             description: Invalid ID supplied
           '404':
             description: Pet not found
           '422':
             description: Validation exception
       post:
         tags:
           - pet
         summary: Add a new pet to the store
         description: Add a new pet to the store
         operationId: addPet
         requestBody:
           description: Create a new pet in the store
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Pet'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Pet'
           required: true
         responses:
           '200':
             description: Successful operation
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/Pet'
           '400':
             description: Invalid input
           '422':
             description: Validation exception
     /pet/findByStatus:
       get:
         tags:
           - pet
         summary: Finds Pets by status
         description: Multiple status values can be provided with comma separated strings
         operationId: findPetsByStatus
         parameters:
           - name: status
             in: query
             description: Status values that need to be considered for filter
             required: false
             explode: true
             schema:
               type: string
               default: available
               enum:
                 - available
                 - pending
                 - sold
         responses:
           '200':
             description: successful operation
             content:
               application/json:
                 schema:
                   type: array
                   items:
                     $ref: '#/components/schemas/Pet'          
               application/xml:
                 schema:
                   type: array
                   items:
                     $ref: '#/components/schemas/Pet'
           '400':
             description: Invalid status value
   components:
     schemas:
       Category:
         type: object
         properties:
           id:
             type: integer
             format: int64
             example: 1
           name:
             type: string
             example: Dogs
         xml:
           name: category
       Tag:
         type: object
         properties:
           id:
             type: integer
             format: int64
           name:
             type: string
         xml:
           name: tag
       Pet:
         required:
           - name
           - photoUrls
         type: object
         properties:
           id:
             type: integer
             format: int64
             example: 10
           name:
             type: string
             example: doggie
           category:
             $ref: '#/components/schemas/Category'
           photoUrls:
             type: array
             xml:
               wrapped: true
             items:
               type: string
               xml:
                 name: photoUrl
           tags:
             type: array
             xml:
               wrapped: true
             items:
               $ref: '#/components/schemas/Tag'
           status:
             type: string
             description: pet status in the store
             enum:
               - available
               - pending
               - sold
         xml:
           name: pet

导入具有API网关扩展字段的OAS格式定义

详见导出标准OAS定义。