Cara mengimpor beberapa API yang sesuai dengan OAS sekaligus - API Gateway

API Gateway memungkinkan Anda untuk mengimpor definisi API yang mengikuti Standar OpenAPI Specification (OAS) 2.0 atau 3.0. Untuk informasi lebih lanjut tentang OAS, lihat OpenAPI Specification. Anda dapat mengimpor definisi API yang sesuai dengan OAS atau mengimpor definisi API yang sesuai dengan OAS yang berisi ekstensi API Gateway.

Impor Definisi API yang Sesuai dengan OAS

Proses:

Tentukan grup API tempat Anda ingin mengimpor API dan konfigurasikan pengaturan global.
Masukkan definisi API yang sesuai dengan OAS 2.0 atau OAS 3.0.
Lakukan pra-pemeriksaan terhadap definisi API dan perbaiki masalah berdasarkan hasil pra-pemeriksaan.
Impor definisi API.

Setelah definisi API diimpor, API dibuat dalam grup API yang ditentukan. Kemudian, Anda dapat menerbitkan API ke lingkungan pilihan Anda dan men-debug API tersebut. Untuk informasi lebih lanjut, lihat Debug API.

Masuk ke Konsol API Gateway.
Di panel navigasi di sebelah kiri, pilih Manage APIs > APIs.
Di halaman API, klik Impor Data yang Sesuai dengan Swagger.

Di kotak dialog Catatan, klik OAS Standar untuk pergi ke halaman Impor Data yang Sesuai dengan Swagger.

Di bagian Informasi Dasar, konfigurasikan parameter berikut.

Parameter	Deskripsi
Impor ke Grup	Tentukan grup API tempat Anda ingin mengimpor API. Penting Path dasar dari grup API harus sama dengan path dasar dalam definisi API yang sesuai dengan OAS Anda. Jika tidak, definisi gagal diimpor. Untuk informasi lebih lanjut tentang path dasar grup API, lihat Buat Grup API. Untuk informasi lebih lanjut tentang path dasar dalam OAS, lihat Swagger Object.
Timpah	Jika Anda memilih kotak centang dan path permintaan bertentangan dengan permintaan HTTP, API yang ada akan ditimpa. Jika Anda tidak memilih kotak centang dan path permintaan bertentangan dengan permintaan HTTP, pesan kesalahan yang menunjukkan bahwa API sudah ada akan dikembalikan.
Versi Definisi API	OAS 2.0 dan OAS 3.0 didukung.

Di bagian (Opsional) Konfigurasi Global, konfigurasikan pengaturan global untuk API.

Parameter	Deskripsi
Layanan Backend	Tentukan layanan backend tipe HTTP/HTTPS, VPC, Campuran, atau Penemuan Layanan yang dibuat di API Gateway. Nilai default adalah Mock. Untuk informasi lebih lanjut, lihat Gunakan layanan backend untuk membuat dan mengelola API.
Mode Permintaan	Atur parameter ini ke Pass-through atau Map (Filter Out Unknown Parameters). Nilai default adalah Pass-through. Catatan Jika Anda menggunakan mode permintaan pass-through, hanya parameter path yang diimpor. API Gateway mengabaikan parameter lainnya, termasuk query, header, formdata, dan body parameters.
Otentikasi Pemanggil	Atur parameter ini ke Alibaba Cloud App atau Tanpa Otentikasi. Nilai default adalah Alibaba Cloud App. Catatan Layanan backend, mode permintaan, dan otentikasi pemanggil adalah pengaturan global yang berlaku untuk semua API. Jika Anda menggunakan ekstensi yang didukung oleh API Gateway untuk mendeklarasikan pengaturan dalam definisi API yang sesuai dengan OAS 2.0, pengaturan diprioritaskan dalam urutan berikut: definisi API yang sesuai dengan OAS 2.0, definisi global OAS, dan pengaturan global opsional API Gateway. Untuk informasi lebih lanjut tentang ekstensi, lihat bagian "Impor definisi API yang sesuai dengan OAS yang berisi ekstensi API Gateway" dari topik ini. Otentikasi AppCode: Nilai default adalah Nonaktifkan Otentikasi AppCode jika Anda mengatur Otentikasi Pemanggil ke Alibaba Cloud App. Algoritma Tanda Tangan: Nilai default adalah HMAC_SHA256.

Di bagian Definisi API, masukkan definisi API yang sesuai dengan OAS 2.0 dan tentukan salah satu metode impor berikut:
Penting
Setiap metode memungkinkan Anda mengimpor hingga 100 definisi API secara bersamaan.
1. Teks: Masukkan definisi API dalam format YAML atau JSON. Definisi API dapat memiliki panjang hingga 256 KB.
2. URL OSS: Masukkan URL objek Object Storage Service (OSS) tempat definisi API disimpan. Objek harus dalam format JSON atau YAML. URL objek harus mendukung akses anonim. Tidak ada batasan ukuran objek.

Tentukan apakah akan memodifikasi pengaturan default parameter lainnya dalam definisi API. Parameter ini dikonfigurasikan saat Anda mengimpor definisi API, tetapi tidak disediakan di halaman Impor Data yang Sesuai dengan Swagger. Tabel berikut menjelaskan parameter tersebut:

Parameter	Deskripsi
Perlindungan Anti-replay	Secara default, fitur ini dinonaktifkan.
Larang Akses Internet	Secara default, fitur ini dinonaktifkan.
Izinkan Publikasi API ke Alibaba Cloud Marketplace	Secara default, fitur ini dinonaktifkan.

Klik Pra-pemeriksaan. API Gateway melakukan simulasi pada data yang ingin Anda impor dan mengembalikan definisi API dan model dalam definisi API yang sesuai dengan OAS, peringatan, dan kesalahan.
Catatan
Peringatan: Sebelum Anda mengimpor definisi API, Anda dapat mengabaikan peringatan. Dalam hal ini, definisi API yang berisi peringatan diabaikan.
Kesalahan: Anda harus memperbaiki kesalahan. Jika tidak, pengecualian akan dilemparkan.
Konfirmasikan bahwa tidak ada kesalahan dan peringatan, lalu klik Impor Data yang Sesuai dengan Swagger untuk mengimpor API. Proses ini mungkin memerlukan waktu. Jangan tutup browser Anda sebelum proses impor selesai.
Setelah API diimpor, Anda dapat melihat hasil impor API.

Pemetaan antara parameter dalam definisi API yang sesuai dengan OAS 2.0 dan definisi API API Gateway

Catatan

Bagian ini hanya menjelaskan parameter dalam definisi API yang sesuai dengan OAS 2.0 yang dapat dipetakan ke parameter dalam definisi API API Gateway. Jika parameter dalam definisi API yang sesuai dengan OAS 2.0 tidak dapat dipetakan ke API Gateway, impor API tidak terpengaruh.

Objek Swagger
1. BasePath: path dasar dari grup API. Saat Anda mengimpor definisi API, API Gateway memeriksa apakah path dasar dari definisi API sama dengan path dasar dari grup API.
2. Schemes: protokol permintaan dalam definisi API.
Objek Path Item
1. Path: path permintaan dalam definisi API.
2. Method: metode permintaan dalam definisi API. Nilai valid: GET, POST, PUT, HEAD, DELETE, PATCH, dan OPTIONS.
Objek Operation
1. Summary: deskripsi dari definisi API.
2. OperationId: nama API yang sesuai dengan definisi API. Jika bidang ekstensi x-aliyun-apigateway-api-name ada, nama dalam bidang ekstensi digunakan sebagai nama API.
3. Schemes: protokol permintaan dalam definisi API. Schemes dalam Objek Operation memiliki prioritas lebih tinggi daripada Schemes dalam Objek Swagger.
Objek Parameter
1. Name: nama parameter permintaan dalam definisi API.
2. In: lokasi parameter permintaan dalam definisi API. Nilai valid: path, query, head, dan formdata.
3. Description: deskripsi parameter permintaan dalam definisi API.
4. Required: menentukan apakah parameter permintaan dalam definisi API diperlukan.
5. Type: tipe parameter permintaan dalam definisi API.
  1. Nilai valid jika Anda mengatur In ke query, path, atau head: string, number, integer, boolean, dan array.
  2. Nilai valid jika Anda mengatur In ke formdata: string, number, integer, boolean, array, dan file.
6. Format: format parameter permintaan dalam definisi API. Format memiliki prioritas lebih tinggi daripada Type.
  Tabel berikut mencantumkan pemetaan antara tipe parameter dalam OAS dan tipe parameter dalam API Gateway.
  Tipe parameter dalam OAS
  Tipe parameter dalam API Gateway
  String
  String
  Boolean
  Boolean
  Array
  Array
  Int32
  Int
  Int64
  Long
  Double
  Double
  Float
  Float
  File
  File
  Catatan
  1. Jika Anda menggunakan mode permintaan pass-through untuk definisi API, hanya parameter path yang diimpor ke definisi API. API Gateway mengabaikan parameter lainnya, termasuk query, header, formdata, dan body parameters.
  2. Jika Anda menggunakan mode permintaan pass-through untuk definisi API dan tidak menggunakan ekstensi API Gateway, pastikan nilai yang sama ditentukan untuk metode permintaan, path permintaan, dan definisi parameter dalam parameter permintaan definisi API dan dalam layanan backend.
  3. Jika parameter dalam badan permintaan dirujuk, parameter tersebut ditampilkan saat dokumen dibuat, tetapi tidak ditampilkan dalam definisi API API Gateway.
Objek Response
1. Kode Status HTTP: kode status HTTP yang terkandung dalam definisi kode kesalahan respons yang didefinisikan dalam definisi API.
2. Description: deskripsi dalam definisi kode kesalahan dalam respons contoh dalam definisi API.
3. Schema: model yang terkandung dalam definisi kode kesalahan respons yang didefinisikan dalam definisi API.
Objek Definitions
Objek dalam definisi API. Saat Anda mengimpor definisi API, API Gateway membuat model dalam grup API yang Anda tentukan. Di halaman Grup API, Anda dapat mengklik Kelola Model di kolom Tindakan grup API untuk melihat definisi model.

Contoh kode berikut memberikan contoh cara mendefinisikan definisi API yang sesuai dengan OAS 2.0 untuk membantu Anda memahami fitur ini. Dalam contoh ini, definisi API Swagger Petstore digunakan.

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"

Pemetaan antara parameter dalam definisi API yang sesuai dengan OAS 3.0 dan definisi API API Gateway

Catatan

Bagian ini menjelaskan bidang yang dipetakan antara definisi API yang sesuai dengan OAS 3.0 dan definisi API API Gateway. Bidang yang tidak dipetakan tidak memengaruhi impor API.

Objek Path Item
1. Path: path permintaan dalam definisi API.
2. Method: metode permintaan dalam definisi API. Nilai valid: GET, POST, PUT, HEAD, DELETE, PATCH, dan OPTIONS.
Objek Operation
1. Summary: deskripsi dari definisi API.
2. OperationId: nama API yang sesuai dengan definisi API. Jika bidang ekstensi x-aliyun-apigateway-api-name ada, nama dalam bidang ekstensi digunakan sebagai nama API.
Objek Parameter
1. Name: nama parameter permintaan dalam definisi API.
2. In: lokasi parameter permintaan dalam definisi API. Nilai valid: path, query, head, dan formdata.
3. Required: menentukan apakah parameter permintaan dalam definisi API diperlukan.
Objek Schema
1. Description: deskripsi parameter permintaan dalam definisi API.
2. Type: tipe parameter permintaan dalam definisi API.
  1. Nilai valid jika Anda mengatur In ke query, path, atau head: string, number, integer, boolean, dan array.
  2. Nilai valid jika Anda mengatur In ke formdata: string, number, integer, boolean, array, dan file.
3. Format: format parameter permintaan dalam definisi API. Format memiliki prioritas lebih tinggi daripada Type.
Objek Request Body
1. Content
  1. application/x-www-form-urlencoded: parameter formdata dalam definisi API.
  2. application/json: Untuk objek yang didefinisikan dalam item ini, API Gateway membuat model dalam grup selama impor. Untuk melihat definisi model, klik Kelola Model di kolom Tindakan di baris yang berisi grup dalam daftar grup.
Objek Responses
1. Kode Status HTTP: kode status HTTP yang terkandung dalam definisi kode kesalahan respons yang didefinisikan dalam definisi API.
2. Description: deskripsi dalam definisi kode kesalahan dalam respons contoh dalam definisi API.
3. Content: model dalam definisi kode kesalahan dalam respons yang didefinisikan dalam definisi API.

Contoh berikut menunjukkan definisi yang sesuai dengan OAS 3.0. Dalam contoh ini, definisi PetStore digunakan.

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

Impor definisi API yang sesuai dengan OAS 2.0 yang berisi ekstensi API Gateway

Untuk informasi lebih lanjut, lihat Ekspor API berdasarkan OAS.

Tipe parameter dalam OAS	Tipe parameter dalam API Gateway
String	String
Boolean	Boolean
Array	Array
Int32	Int
Int64	Long
Double	Double
Float	Float
File	File