Ringkasan OpenAPI

API Gateway mendukung API yang dideskripsikan 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
  • Menggunakan 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 mengenal 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."

OpenAPI 3.x

Jika Anda baru mengenal OpenAPI, lihat struktur dasar Swagger yang menyediakan contoh dokumen OpenAPI dan menjelaskan setiap bagian file. Contoh berikut mengilustrasikan struktur dasar ini:

openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Get the name of an airport from its three-letter IATA code
  version: 1.0.0
x-google-api-management:
  backend:
    BACKEND_NAME
      address: https://BACKEND_URL/airportNameGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
x-google-backend: BACKEND_NAME
paths:
  /airportName:
    get:
      summary: Get the airport name for a given IATA code
      operationId: airportName
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string
      parameters:
        - name: iataCode
          in: query
          required: true
          schema:
            type: string

Selain struktur dasar, gunakan file openapi.yaml untuk mengonfigurasi:

Membuat dokumen OpenAPI

Bergantung pada bahasa yang Anda gunakan, Anda mungkin dapat membuat dokumen OpenAPI. Di Java, ada project open source untuk Jersey dan Spring yang dapat membuat dokumen OpenAPI dari anotasi. Terdapat juga plugin Maven. Untuk developer Python dan Node, OpenAPI.Tools mungkin merupakan project yang menarik.

Komunitas OpenAPI terus mengembangkan alat untuk membantu komposisi (dan, untuk beberapa bahasa, pembuatan otomatis) dokumen OpenAPI. Lihat Spesifikasi OpenAPI untuk mengetahui informasi selengkapnya.

Langkah berikutnya