Ringkasan OpenAPI

Cloud Endpoints 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 mendeskripsikan API dalam file JSON atau 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. Lihat Cloud Endpoints Portal untuk mengetahui informasi selengkapnya.

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

  • Buat library klien dalam puluhan bahasa.
  • Buat stub server.
  • Gunakan project untuk memverifikasi kepatuhan dan membuat sampel.

Struktur dasar dokumen OpenAPI

Dokumen OpenAPI mendeskripsikan 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. Dokumen OpenAPI dari Panduan memulai Endpoints mengilustrasikan struktur dasar ini:

    swagger: "2.0"
    info:
      title: "Airport Codes"
      description: "Get the name of an airport from its three-letter IATA code."
      version: "1.0.0"
    # This field will be replaced by the deploy_api.sh script.
    host: "YOUR-PROJECT-ID.appspot.com"
    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, file openapi.yaml dari contoh kode yang digunakan dalam tutorial menunjukkan:

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 pengguna Python, flask-swagger mungkin merupakan project yang menarik, dan swagger-node-express untuk developer Node.

Komunitas OpenAPI terus mengembangkan alat untuk membantu komposisi (dan, untuk beberapa bahasa, pembuatan otomatis) dokumen OpenAPI. Lihat situs Swagger untuk mengetahui daftar lengkap alat dan integrasi.

Langkah selanjutnya