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:
- Cara mengonfigurasi jalur untuk menggunakan kunci API.
- Berbagai skema keamanan untuk autentikasi.
- Ekstensi OpenAPI tersedia untuk Endpoints API.
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
- Ekstensi OpenAPI
- Fitur OpenAPI yang tidak didukung
- Mengonfigurasi Endpoint
- Men-deploy Konfigurasi Endpoint