Pengetikan API REST untuk pengembang frontend

Saat ini, pendekatan berikut ini banyak digunakan untuk menggambarkan interaksi browser dan server, seperti OpenApi & GraphQL.

Pada artikel ini, saya akan berbicara tentang upaya kami untuk membuat REST API yang diketik secara statis dan menyelamatkan tim front-end dari penulisan kode untuk menulis permintaan data, menyederhanakan pengujian dan mengurangi jumlah kemungkinan kesalahan.



Alat-alat ini membantu kami:

• Desain dan model API sesuai standar berdasarkan spesifikasi
• Buat kode yang stabil dan dapat digunakan kembali untuk API Anda di hampir semua bahasa
• Tingkatkan pengalaman pengembang dengan dokumentasi API interaktif
• Mudah melakukan tes fungsional pada API Anda.
• Buat dan terapkan pedoman gaya API terbaik dalam arsitektur API Anda

Gagasan utama dari pendekatan ini adalah bahwa dengan memiliki tipe data yang sama pada klien dan server, lebih sulit bagi pengembang dalam tim untuk membuat kesalahan pada klien, dan menggunakan pembuatan kode tidak perlu ditulis, dipelihara dan, karenanya, ditutupi dengan unit test.

Aplikasi frontend tidak akan dikompilasi jika perintah membuat kesalahan dalam tipe data yang menerima / persediaan REST API.

Dengan demikian, dengan memiliki kode yang diketik secara statis pada klien, kami dapat menyingkirkan kesalahan bodoh yang terkait dengan jenis dan memastikan bahwa kode kami sepenuhnya kompatibel dengan versi API saat ini.

Untuk mendapatkan semua keuntungan dari API yang diketik secara statis di atas, kita perlu menggunakan generator kode yang, sesuai dengan spesifikasi OpenAPI, dapat menghasilkan file deskripsi jenis, untuk Filescript ini adalah file * .d.ts.

Proyek kami menggunakan arsitektur microservice dan seluruh backend ditulis dalam .NET, jadi kami menggunakan NSwag untuk menghasilkan klien API untuk frontend / backend. Alat ini memungkinkan Anda untuk menghasilkan dokumen OpenAPI, yang kemudian digunakan untuk menghasilkan kode klien.

Arsitektur

Secara umum, proses pembuatan kode terdiri dari beberapa tahap:

• Pembuatan Dokumen OpenAPI
• Membuat kode menggunakan dokumen OpenAPI

Dalam kasus kami, backend ditulis menggunakan .Net dan bahasa pengembangan C # utama adalah karena pilihan alat. Kami menggunakan alat yang sama yang disebut NSwag untuk menghasilkan dokumen dan klien OpenAPI.


Gambar 1 Arsitektur solusi untuk menghasilkan kode klien sisanya

Angka tersebut menunjukkan:

• Microservice 1 ... N - microservices menyediakan API
• NSwag - membuat dokumen OpenAPI dari kode API microservice (layanan microser dapat ditulis dalam bahasa apa pun yang ada alat untuk membuat dokumen OpenAPI)
• NSwag - menghasilkan kode API klien untuk dokumentasi OpenAPI (ada banyak alat yang dapat Anda pilih yang lebih sesuai dengan tumpukan teknologi Anda)
• OpenAPI doc - Dokumentasi OpenAPI dibuat
• API Client 1 ... N - klien yang mengkonsumsi data API (dapat diimplementasikan pada bahasa apa saja yang mendukung generator untuk NSwag C # dan Typecript)
• SPA 1 ... N - Aplikasi Frontend, dalam kasus kami React (NSwag mendukung pembuatan klien untuk AngularJS / Angular, React (fetch), JQuery (Promise / Callback), Aurelia)

Urutan tindakan adalah sebagai berikut:

• Tandai pengontrol API dengan tag / atribut / dekorator yang sesuai tergantung pada bahasa API
• Hasilkan Dokumentasi Kode API OpenAPI
• Hasilkan kode API klien menggunakan dokumentasi OpenAPI
• Integrasikan kode API klien ke dalam aplikasi data konsumen API

Dokumentasi

Agar dapat menghasilkan kode, kita perlu menjelaskan jenis nilai yang diterima / dikembalikan dari pengontrol API, dalam contoh ini, di mana bahasa C # digunakan, menggunakan atribut SwaggerOperation, kami menandai metode yang akan mengembalikan daftar semua kuesioner di server, dalam kode klien, metode untuk mendapatkan Data akan disebut GetAllQuestionnaires:

[HttpGet, Route("")] [SwaggerOperation(OperationId = "GetAllQuestionnaires")] [SuccessResponse(typeof(IEnumerable<QuestionnaireViewModel>))] public IEnumerable<QuestionnaireViewModel> Get() { var surveys = _questionnaireRepository.GetAll(); return surveys.Select(QuestionnaireViewModel.ToViewModel).ToArray(); } 

Daftar 1 Contoh kode C # yang menjelaskan metode API

Kemudian, menggunakan NSwag, kami secara otomatis menghasilkan dokumen OpenAPI yang akan berisi semua titik akhir API yang telah ditandai dengan atribut yang sesuai dalam kode backend.


Gambar 2 Dokumen OpenAPI

Karenanya, kami berhasil membuat dokumentasi API kami yang selalu diperbarui secara otomatis.

Mengetik

Dokumentasi OpenAPI berisi informasi tentang jenis data yang akan dikirim / diterima oleh pengendali backend. Jadi, di sisi front-end, kita dapat sepenuhnya bergantung pada jenis yang disediakan backend kepada kita dan tidak membuat jenis kita sendiri, tetapi mengimpornya dari kode klien yang dihasilkan menggunakan dokumen OpenAPI.

Sebagai contoh kami, dokumen berisi informasi tentang jenis QuestionnaireViewModel (di sini spesifikasi disajikan dalam bentuk HTML untuk dibaca)


Gambar 3 Contoh model data dalam dokumen OpenAPI

Langkah selanjutnya adalah meneruskan informasi ini ke kode aplikasi frontend.

Pembuatan kode

Kami juga menggunakan NSwag untuk menghasilkan kode API klien. Pada input, ia menerima dokumen OpenAPI dan menghasilkan kode API klien sesuai dengan pengaturan yang ditentukan. Untuk bagian depan, di sebelah kode yang diterima, kami menambahkan package.json dan mengirimkannya ke register npm lokal kami.

Seperti yang Anda lihat dari daftar kode backend (lihat Listing 1), kami menandai metode pengontrol menggunakan atribut

 [SwaggerOperation(OperationId = "GetAllQuestionnaires")] 

OperationId yang ditentukan dalam atribut C # dalam kasus kami akan menjadi nama metode klien.


Gambar 4 Contoh penggunaan API klien yang dihasilkan

Selain itu, setelah menghasilkan klien, kami menerima file d.ts yang berisi deskripsi tipe data yang sesuai, yang ditunjukkan pada gambar di bawah ini.


Gambar 5 Contoh deskripsi tipe data dalam file .d.ts

Sekarang di kode aplikasi frontend, Anda dapat menggunakan tipe data yang diekspor dari kode API klien dan menggunakan pelengkapan otomatis dalam editor kode, contoh ditunjukkan pada gambar di bawah ini.


Gambar 6 Contoh penggunaan informasi tipe data API klien

Semua validator tipe data yang relevan dalam naskah juga berfungsi.

Contoh pada gambar di bawah ini.


Gambar 7 Contoh validasi tipe data API klien


Gambar 8 Contoh validasi tipe data API klien

Kesimpulan

Setelah menerapkan pendekatan ini, kami menerima keuntungan berikut:

• Lebih sedikit bug tipe data
• Lebih sedikit kode, lebih sedikit tenaga untuk debugging, pengujian, dukungan
• Dokumentasi selalu terbaru untuk semua metode API untuk masing-masing layanan microser
• Kemampuan untuk menguji otomatisasi API
• Sistem tipe terpadu untuk frontend dan backend

Referensi

• Spesifikasi OpenAPI
• Situs Proyek NSWAG