Ringkasan OpenAPI

API Gateway mendukung API yang dijelaskan menggunakan versi yang didukung dari spesifikasi OpenAPI.

API Anda dapat diterapkan menggunakan framework REST yang tersedia secara publik seperti Django atau Jersey.

Anda mendeskripsikan API dalam file YAML yang disebut sebagai dokumen OpenAPI. Halaman ini menjelaskan beberapa manfaat penggunaan OpenAPI, menampilkan dokumen OpenAPI dasar, dan memberikan informasi tambahan untuk membantu Anda memulai penggunaan OpenAPI.

Versi OpenAPI yang Didukung

API Gateway mendukung versi OpenAPI berikut:

  1. OpenAPI 2.0 (sebelumnya Swagger)
  2. OpenAPI 3.0.x

Spesifikasi resmi untuk setiap versi tersedia dari OpenAPI Initiative.

Dukungan Versi Patch

Spesifikasi OpenAPI menunjukkan bahwa versi patch (misalnya, 3.0.1, 3.0.2) hanya memperkenalkan perbaikan atau klarifikasi dan tidak menambahkan fitur baru. Oleh karena itu, API Gateway mendukung semua versi patch 3.0.

Terminologi

Di seluruh dokumentasi API Gateway, OpenAPI 3.x mengacu pada semua versi yang didukung OpenAPI 3, seperti yang dijelaskan dalam Versi OpenAPI yang didukung.

Manfaat

Salah satu manfaat utama penggunaan OpenAPI adalah untuk dokumentasi; setelah Anda memiliki dokumen OpenAPI yang mendeskripsikan API, Anda dapat membuat dokumentasi referensi untuk API Anda.

Ada manfaat lain dari penggunaan OpenAPI. Misalnya, Anda dapat:

  • Membuat library klien dalam lusinan bahasa
  • Membuat stub server
  • Gunakan project untuk memverifikasi kepatuhan Anda dan membuat sampel

Struktur dasar dokumen OpenAPI

Dokumen OpenAPI mendeskripsikan tampilan REST API Anda, dan menentukan informasi seperti:

  • Nama dan deskripsi API
  • Setiap endpoint (jalur) dalam API
  • Cara pemanggil diautentikasi

Struktur dokumen OpenAPI Anda bergantung pada versi OpenAPI yang Anda gunakan. Contoh berikut menjelaskan struktur OpenAPI 2.0 dan OpenAPI 3.x.

OpenAPI 2.0

Jika Anda baru menggunakan OpenAPI, lihat struktur dasar Swagger, yang menyediakan contoh dokumen OpenAPI (juga disebut sebagai spesifikasi Swagger) dan menjelaskan secara singkat setiap bagian file. Contoh berikut mengilustrasikan struktur dasar ini:

swagger: "2.0"
info:
  title: API_ID optional-string
  description: "Get the name of an airport from its three-letter IATA code."
  version: "1.0.0"
host: DNS_NAME_OF_DEPLOYED_API
schemes:
  - "https"
paths:
  "/airportName":
    get:
      description: "Get the airport name for a given IATA code."
      operationId: "airportName"
      parameters:
        -
          name: iataCode
          in: query
          required: true
          type: string
      responses:
        200:
          description: "Success."
          schema:
            type: string
        400:
          description: "The IATA code is invalid or missing."