Ringkasan OpenAPI

Cloud Endpoints mendukung API yang dijelaskan menggunakan versi yang didukung dari spesifikasi OpenAPI.

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

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

Versi OpenAPI yang Didukung

Cloud Endpoints 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, Cloud Endpoints mendukung semua versi patch 3.0.

Terminologi

Di seluruh dokumentasi Cloud Endpoints, OpenAPI 3.x mengacu pada semua versi yang didukung OpenAPI 3.

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:

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

Struktur dasar dokumen OpenAPI

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

  • Nama dan deskripsi API.
  • Setiap endpoint (jalur) dalam API.
  • Cara autentikasi penelepon.

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 situs Swagger basic structure, 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: API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
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 spesifikasi OpenAPI, 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
servers:
  - url: https://API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
    x-google-endpoint: {}
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, file openapi.yaml dari kode sampel yang digunakan dalam tutorial mengilustrasikan:

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 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 berikutnya