Impor file Swagger untuk membuat API dengan ekstensi API Gateway - API Gateway

Swagger adalah serangkaian spesifikasi yang banyak digunakan untuk mendefinisikan dan menggambarkan API layanan backend. API Gateway memungkinkan Anda mengimpor file berdasarkan spesifikasi Swagger 2.0. Anda dapat menggunakan operasi ImportSwagger atau konsol untuk mengimpor data sesuai dengan Swagger, seperti ditunjukkan pada gambar berikut.

Ekstensi Swagger API Gateway didasarkan pada Swagger 2.0. Anda dapat membuat definisi berbasis Swagger untuk API dan mengimpor file Swagger ke dalam konsol API Gateway untuk membuat atau memperbarui beberapa API sekaligus. API Gateway mendukung Swagger 2.0 secara default dan kompatibel dengan sebagian besar versi spesifikasi Swagger. Namun, ada perbedaan implementasi antara Swagger 2.0 dan versi spesifikasi Swagger lainnya.

Topik ini menjelaskan ekstensi Swagger API Gateway dan memberikan contoh implementasinya.

Catatan

All the parameters and their values in Swagger are case-sensitive.

1. Ekstensi yang didukung oleh Swagger

Swagger mendukung ekstensi terhadap Operation Object asli. Ekstensi digunakan untuk menyediakan fitur otentikasi, pemetaan parameter, dan tujuan layanan backend. Selain itu, ekstensi x-aliyun-apigateway-any-method digunakan untuk menentukan metode HTTP yang dapat digunakan pemanggil API untuk memanggil API. Semua ekstensi terkait dengan API Gateway dimulai dengan x-aliyun-apigateway-. Bagian berikut menjelaskan ekstensi tersebut.

1.1 x-aliyun-apigateway-auth-type: Tipe Otorisasi

Berlaku untuk Operation Object dan menentukan tipe otorisasi API.

Valid values:

APP (default): Aplikasi Alibaba Cloud harus digunakan sebagai identitas untuk memanggil API.
ANONYMOUS: Pengguna mana pun dapat memanggil API tanpa menggunakan aplikasi sebagai identitas.

Example:

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-auth-type: ANONYMOUS
...

1.2 x-aliyun-apigateway-api-market-enable: Publikasi ke Alibaba Cloud Marketplace

Berlaku untuk Operation Object dan menentukan apakah API diterbitkan ke Alibaba Cloud Marketplace.

Valid values:

true
false (default)

Example:

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-api-market-enable: true
...

1.3 x-aliyun-apigateway-api-force-nonce-check: Verifikasi Nonce Paksa

Berlaku untuk Operation Object dan menentukan apakah akan melakukan verifikasi nonce paksa pada API.

Valid values:

true
false (default)

Example:

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-api-force-nonce-check: true
...

1.4 x-aliyun-apigateway-parameter-handling: Pemetaan API

Berlaku untuk Operation Object dan menentukan pemetaan antara parameter permintaan dan parameter layanan backend. Jika Anda memilih PASSTHROUGH, Parameter Object tidak mendukung x-aliyun-apigateway-backend-location dan x-aliyun-apigateway-backend-name.

Valid values:

PASSTHROUGH (default): Parameter permintaan dilewatkan ke layanan backend tanpa pemetaan.
MAPPING: Parameter permintaan dipetakan ke parameter layanan backend.

Example:

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-parameter-handling: MAPPING
...

1.5 x-aliyun-apigateway-backend: Tipe Layanan Backend

Berlaku untuk Operation Object dan menentukan tipe layanan backend. Properti spesifik bervariasi berdasarkan tipe layanan backend. Untuk detailnya, lihat tabel berikut.

1.5.1 HTTP

Tipe ini digunakan dalam skenario di mana layanan backend dapat diakses secara langsung. Anda dapat langsung mengonfigurasi URL untuk layanan backend tipe ini.

Property description:

Properti	Tipe	Deskripsi
type	string	Wajib. Nilainya adalah HTTP.
address	string	Wajib. URL layanan backend.
path	string	Opsional. Path layanan backend. Nilainya bisa berupa variabel. Secara default, nilai properti ini sama dengan path root.
method	string	Wajib. Metode permintaan backend.
timeout	int	Opsional. Nilai default adalah 10000. Nilai valid: 500 hingga 30000.

Example:

...
x-aliyun-apigateway-backend:
  type: HTTP
  address: 'http://www.aliyun.com'
  path: '/builtin/echo'
  method: get
  timeout: 10000
...

1.5.2 HTTP-VPC

Jika layanan backend berjalan pada virtual private cloud (VPC), tipe ini digunakan. Untuk mengonfigurasi layanan backend, Anda harus terlebih dahulu membuat otorisasi akses VPC. Untuk informasi lebih lanjut, lihat topik yang menjelaskan cara membuat API dengan sumber daya di VPC sebagai layanan backend.

Property description:

Properti	Tipe	Deskripsi
type	string	Wajib. Nilainya adalah HTTP-VPC.
vpcAccessName	string	Wajib. Nama otorisasi akses VPC yang digunakan untuk mengakses layanan backend.
path	string	Opsional. Path layanan backend. Nilainya bisa berupa variabel. Secara default, nilai properti ini sama dengan path root.
method	string	Wajib. Metode permintaan backend.
timeout	int	Opsional. Nilai default adalah 10000. Nilai valid: 500 hingga 30000.

Example:

...
x-aliyun-apigateway-backend:
  type: HTTP_VPC
  vpcAccessName: vpcAccess1
  path: '/users/{userId}'
  method: GET
  timeout: 10000
...

1.5.3 FC

Jika layanan backend adalah Function Compute, Anda harus menyetel tipe layanan backend ke FC.

Property description:

Properti	Tipe	Deskripsi
type	string	Wajib. Nilainya adalah FC.
fcRegion	string	Wajib. Wilayah tempat layanan dan fungsi Function Compute Anda diterapkan.
serviceName	string	Wajib. Nama layanan di Function Compute.
functionName	string	Wajib. Nama fungsi di Function Compute.
arn	string	Opsional. Otorisasi Resource Access Management (RAM) untuk Function Compute.

Example:

...
x-aliyun-apigateway-backend:
  type: FC
  fcRegion: cn-shanghai
  serviceName: fcService
  functionName: fcFunction
  arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
...

1.5.4 MOCK

Tipe ini digunakan untuk mensimulasikan hasil pengembalian yang diharapkan.

Property description:

Properti	Tipe	Deskripsi
type	string	Wajib. Nilainya adalah MOCK.
mockResult	string	Wajib. Hasil simulasi.
mockStatusCode	Integer	Opsional.
mockHeaders	Header	Opsional.

Deskripsi Header:

Properti	Tipe	Deskripsi
name	string	Wajib
value	string	Wajib

Example:

...
x-aliyun-apigateway-backend:
        type: MOCK
        mockResult: mock resul sample
        mockStatusCode: 200
        mockHeaders:
          - name: server
            value: mock
          - name: proxy
            value: GW
...

1.6 x-aliyun-apigateway-constant-parameters: Parameter Konstan

Berlaku untuk Operation Object dan mendefinisikan parameter konstan yang selalu diterima oleh layanan backend. Anda tidak perlu menyertakan parameter ini dalam permintaan yang dikirim ke layanan backend.

Property description:

Properti	Tipe	Deskripsi
backendName	string	Wajib. Nama parameter konstan.
value	string	Wajib. Nilai parameter konstan.
location	String	Wajib. Lokasi parameter konstan. Nilai valid: query dan header.
description	string	Opsional. Deskripsi parameter konstan.

Example:

      ...
      x-aliyun-apigateway-constant-parameters:
        - backendName: swaggerConstant
          value: swaggerConstant
          location: header
          description: deskripsi dari swagger
      ...

1.7 x-aliyun-apigateway-system-parameters: Parameter Sistem Layanan Backend

Berlaku untuk Operation Object dan menentukan parameter sistem layanan backend.

Property description:

Properti	Tipe	Deskripsi
systemName	string	Wajib. Nama parameter sistem.
backendName	string	Wajib. Nama parameter sistem yang dipetakan di layanan backend.
location	String	Wajib. Lokasi parameter sistem. Nilai valid: query dan header.

Example:

    ...
    x-aliyun-apigateway-system-parameters:
        - systemName: CaAppId
          backendName: appId
          location: header
   ...

1.8 x-aliyun-apigateway-backend-location: Lokasi Parameter Backend

Berlaku untuk Parameter Object dan menentukan lokasi pemetaan parameter permintaan di layanan backend. Ekstensi ini hanya berlaku ketika x-aliyun-apigateway-parameter-handling disetel ke MAPPING.

Valid values:

path
header
query
formData

Example:

     ...
      parameters:
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      ...

1.9 x-aliyun-apigateway-backend-name: Nama Parameter Backend

Berlaku untuk Parameter Object dan menentukan nama pemetaan parameter permintaan di layanan backend. Ekstensi ini hanya berlaku ketika x-aliyun-apigateway-parameter-handling disetel ke MAPPING.

Example:

      ...
      parameters:
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      ...

1.10 x-aliyun-apigateway-query-schema: Definisi Skema untuk Parameter Query

Berlaku untuk Parameter Object dan mendefinisikan skema untuk parameter query. Ekstensi ini dapat digunakan ketika parameter bertipe STRING dan didefinisikan sebagai parameter query.

Example:

      ...
      parameters:
        - name: event_info				
          in: query
          required: true
          type: string
          x-aliyun-apigateway-query-schema:
            $ref: "#/definitions/EvnetInfo"
      ...

1.11 x-aliyun-apigateway-any-method: Metode ANY

Berlaku untuk Path Item Object dan menentukan metode HTTP yang dapat digunakan untuk memanggil API.

Example:

...
paths:
  'path/':
     x-aliyun-apigateway-any-method:
     ...
...

1.12 x-aliyun-apigateway-app-code-type: Otentikasi Sederhana Berbasis AppCode

Berlaku untuk Operation Object dan menentukan apakah API mendukung otentikasi sederhana berbasis AppCode.

Valid values:

DEFAULT (default): Otentikasi sederhana berbasis AppCode diaktifkan.
DISABLE: Otentikasi sederhana berbasis AppCode dinonaktifkan.
HEADER: AppCode dibawa sebagai header dalam permintaan.
HEADER_QUERY: AppCode dibawa sebagai header atau parameter Query dalam permintaan.

Example:

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-app-code-type: HEADER
...

2. Kompatibilitas

API Gateway dan spesifikasi Swagger mendefinisikan API dengan cara yang berbeda.

2.1 Tipe Parameter

Tipe parameter di Swagger	Tipe parameter di API Gateway	Parameter verifikasi yang didukung dan aturannya
type:integer format:int32	Int	mininum maxnum
type:integer format:int64	Long	mininum maxnum
type:number format:float	Float	mininum maxnum
type:number format:double	Double	mininum maxnum
type:string	String	maxLength enumValues pattern
type:boolean format:Boolean	Boolean	-

2.2 Dukungan untuk Field Consumes

Jika file konfigurasi Swagger berisi parameter formData, field consumes harus dikonfigurasi. Di API Gateway, field ini hanya dapat disetel ke application/x-www-form-urlencoded.

consumes:
  - application/x-www-form-urlencoded

3. Contoh ekstensi Swagger

Bagian ini menyediakan empat contoh ekstensi Swagger untuk API Gateway. Contoh-contoh tersebut mencakup hampir semua aspek dari ekstensi Swagger. Anda dapat merujuk pada contoh-contoh ini saat mendefinisikan API berdasarkan ekstensi Swagger.

Catatan

Contoh-contoh ini hanya untuk referensi.

3.1 Contoh dengan HTTP sebagai Tipe Layanan Backend

swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
  - https
x-aliyun-apigateway-parameter-handling: MAPPING
x-aliyun-apigateway-api-market-enable: true
x-aliyun-apigateway-api-force-nonce-check: true
x-aliyun-apigateway-backend:
  type: HTTP
  address: 'http://www.aliyun.com'
  method: get
  timeout: 10000
paths:
  '/http/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-api-market-enable: true
      x-aliyun-apigateway-auth-type: ANONYMOUS
      parameters:
        - name: userId
          in: path
          required: true
          type: string
        - name: swaggerQuery
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      x-aliyun-apigateway-constant-parameters:
        - backendName: swaggerConstant
          value: swaggerConstant
          location: header
          description: deskripsi dari swagger
      x-aliyun-apigateway-system-parameters:
        - systemName: CaAppId
          backendName: appId
          location: header
      responses:
        '200':
          description: deskripsi 200
        '400':
          description: deskripsi 400
  '/echo/test/post/{userId}':
    post:
      operationId: testpost
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP
        address: 'http://www.aliyun.com'
        method: post
        timeout: 10000
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: userId
          required: true
          in: path
          type: string
        - name: swaggerQuery1
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          x-aliyun-apigateway-enum: 1,2,3
        - name: swaggerQuery2
          in: query
          required: false
          type: string
          x-aliyun-apigateway-backend-location: header
          x-aliyun-apigateway-backend-name: backendHeader
          x-aliyun-apigateway-query-schema:
            $ref: '#/definitions/AiGeneratePicQueryVO'
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
        - name: swaggerFormdata
          in: formData
          required: true
          type: string
      responses:
        '200':
          description: deskripsi 200
          schema:
            $ref: '#/definitions/ResultOfGeneratePicturesVO'
        '400':
          description: deskripsi 400
    x-aliyun-apigateway-any-method:
      operationId: case2
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP
        address: 'http://www.aliyun.com'
        path: '/builtin/echo/{abc}'
        method: post
        timeout: 10000
      parameters:
        - name: userId
          in: path
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          x-aliyun-apigateway-backend-name: abc
          x-aliyun-apigateway-backend-location: path
      responses:
        '200':
          description: deskripsi 200
        '400':
          description: deskripsi 400
definitions:
  AiGeneratePicQueryVO:
    type: object
    properties:
      transactionId:
        type: string
        description: ID tugas asinkron
  GeneratePictureVO:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: ID gambar
      name:
        type: string
        description: nama gambar
  GeneratePicturesVO:
    type: object
    properties:
      failSize:
        type: integer
        format: int64
        description: jumlah kegagalan
      list:
        type: array
        description: daftar gambar
        items:
          $ref: '#/definitions/GeneratePictureVO'
          title: GeneratePictureVO
      successSize:
        type: integer
        format: int32
        description: jumlah keberhasilan
      totalSize:
        type: number
        format: float
        description: total jumlah permintaan
  ResultOfGeneratePicturesVO:
    type: object
    properties:
      model:
        description: konten yang dikembalikan
        $ref: '#/definitions/GeneratePicturesVO'
        title: GeneratePicturesVO
      requestId:
        type: string
        description: ID permintaan

3.2 Contoh dengan HTTP-VPC sebagai Tipe Layanan Backend

swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
  - https
paths:
  '/http/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP-VPC
        vpcAccessName: vpcName1
        path: '/builtin/echo/{userId}'
        method: get
        timeout: 10000
      parameters:
        - name: userId
          in: path
          required: true
          type: string
        - name: swaggerQuery
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      responses:
        '200':
          description: deskripsi 200
        '400':
          description: deskripsi 400
  '/echo/test/post':
    post:
      operationId: testpost
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP-VPC
        vpcAccessName: vpcName2
        path: '/builtin/echo'
        method: post
        timeout: 10000
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: swaggerQuery1
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        - name: swaggerQuery2
          in: query
          required: false
          type: string
          x-aliyun-apigateway-backend-location: header
          x-aliyun-apigateway-backend-name: backendHeader
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
        - name: swaggerFormdata
          in: formData
          required: true
          type: string
      responses:
        '200':
          description: deskripsi 200
        '400':
          description: deskripsi 400
    x-aliyun-apigateway-any-method:
      operationId: case2
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: PASSTHROUGH
      x-aliyun-apigateway-backend:
        type: HTTP-VPC
        vpcAccessName: vpcName3
        path: '/builtin/echo'
        method: post
        timeout: 10000
      responses:
        '200':
          description: deskripsi 200
        '400':
          description: deskripsi 400

3.3 Contoh dengan FC sebagai Tipe Layanan Backend

swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
  - https
paths:
  '/http/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: FC
        fcRegion: cn-shanghai
        serviceName: fcService
        functionName: fcFunction
        arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: deskripsi 200
        '400':
          description: deskripsi 400

3.4 Contoh dengan MOCK sebagai Tipe Layanan Backend

swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
paths:
  '/mock/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: MOCK
        mockResult: mock resul sample
        mockStatusCode: 200
        mockHeaders:
          - name: server
            value: mock
          - name: proxy
            value: GW
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: deskripsi 200
        '400':
          description: deskripsi 400

4. Catatan penggunaan

Pay attention to the following instructions, which may affect Swagger importing.

4.1 Ruang Lingkup Ekstensi

Beberapa ekstensi menggunakan nilai global jika ekstensi tidak ditentukan untuk API tertentu. Jika nilai berbeda ditentukan secara individual untuk API tertentu, nilai yang ditentukan secara individu akan berlaku. Berikut adalah daftar ekstensi tersebut.

x-aliyun-apigateway-backend
x-aliyun-apigateway-api-market-enable
x-aliyun-apigateway-api-force-nonce-check
x-aliyun-apigateway-parameter-handling
x-aliyun-apigateway-auth-type

4.2 Deskripsi Field Definition di Swagger

API Gateway supports model definition in Swagger importing. However, the model definition differs from that in Swagger specifications. Definisi model digunakan untuk menghasilkan SDK. Batasan berikut diberlakukan di atas spesifikasi Swagger:

Tag schema hanya mendukung tipe $ref.
Model di field Definition hanya mendukung definisi model bertipe object.
Array didefinisikan dalam model di field Definition. Jika $ref digunakan untuk referensi, tag title diperlukan. Jika tipe array ditentukan, daftar array juga akan dihasilkan selama pembuatan SDK.