Ringkasan OpenAPI

API Gateway mendukung API yang dijelaskan menggunakan spesifikasi OpenAPI, versi 2.0. API Anda dapat diterapkan menggunakan framework REST yang tersedia secara publik seperti Django atau Jersey.

Anda menjelaskan 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 OpenAPI.

Manfaat

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

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

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

Struktur dasar dokumen OpenAPI

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

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

Jika Anda baru mengenal OpenAPI, lihat situs 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."

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 selanjutnya