Ringkasan OpenAPI

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

Anda dapat mendeskripsikan API 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.

Manfaat

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

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

  • Membuat library klien dalam banyak bahasa
  • Membuat stub server
  • Gunakan project untuk memverifikasi kesesuaian dan membuat contoh

Struktur dasar dokumen OpenAPI

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

  • Nama dan deskripsi API
  • Masing-masing endpoint (jalur) di API
  • Cara pemanggil diautentikasi

Jika Anda baru menggunakan OpenAPI, lihat situs Struktur dasar Swagger, yang menyediakan contoh dokumen OpenAPI (juga disebut sebagai spesifikasi Swagger) dan menjelaskan setiap bagian file secara singkat. 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 digunakan, Anda mungkin dapat membuat dokumen OpenAPI. Di Java, ada project open source untuk Jersey dan Spring yang dapat menghasilkan dokumen OpenAPI dari anotasi. Terdapat juga plugin Maven. Bagi developer Python dan Node, OpenAPI.Tools mungkin merupakan project yang menarik.

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

Langkah selanjutnya