Ringkasan OpenAPI

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

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 menetapkan informasi seperti:

  • Nama dan deskripsi API.
  • Endpoint individual (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. Dokumen OpenAPI dari Panduan memulai endpoint menggambarkan 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 kode contoh yang digunakan dalam tutorial menunjukkan:

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

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

Langkah selanjutnya