Ringkasan OpenAPI

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

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

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

Versi OpenAPI yang Didukung

Gateway API mendukung versi OpenAPI berikut:

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

Spesifikasi resmi untuk setiap versi tersedia dari the 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, Gateway API mendukung semua versi patch 3.0 dan 3.1.

Terminologi

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

Manfaat

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

Ada manfaat lain menggunakan OpenAPI. Misalnya, Anda dapat:

  • Membuat library klien dalam puluhan bahasa
  • Membuat stub server
  • Menggunakan project untuk memverifikasi kesesuaian Anda dan membuat sampel

Struktur dasar dokumen OpenAPI

Dokumen OpenAPI menjelaskan permukaan REST API Anda, dan menentukan informasi seperti:

  • Nama dan deskripsi API
  • Endpoint individual (jalur) di API
  • Cara autentikasi pemanggil

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."

OpenAPI 3.x

Jika Anda baru menggunakan 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:
  backends:
    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. Ada 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