Geekly articles weekly

Dari API pertama di Swagger ke Single kontrak pada RAML

gambar

Hai% nama pengguna%!

Anda mungkin tahu apa itu API dan berapa banyak tergantung pada mereka dalam proyek Anda. Selain itu, saya juga percaya bahwa Anda sudah terbiasa dengan apa pendekatan API pertama dan Anda tahu bahwa Swagger dan Open API adalah beberapa alat yang paling populer untuk membantunya mengikuti.

Tetapi dalam artikel ini saya ingin berbicara tentang pendekatan implementasi API terlebih dahulu, secara konseptual berbeda dari apa yang ditawarkan Swagger dan Apiary. Ide utama adalah konsep kontrak tunggal dan kemungkinan implementasinya berdasarkan RAML 1.0.

Di bawah potongan:

  • Penjelasan singkat tentang prinsip-prinsip API terlebih dahulu;
  • Kontrak tunggal - pengenalan konsep, prasyarat untuk penampilan, pertimbangan kemungkinan penerapannya berdasarkan OAS (Swagger);
  • RAML + anotasi + overlay sebagai basis untuk kontrak tunggal , contoh;
  • Masalah RAML, ketidaksepakatan konseptual pengembang;
  • Ide layanan SaaS berdasarkan ide di atas (gambar prototipe di atas).



Dari API pertama di Swagger ke Single kontrak pada RAML


Ketika merancang sistem perangkat lunak modern, tugas sering muncul untuk mengoordinasi dan mengembangkan antarmuka untuk interaksi komponen mereka satu sama lain. Dalam dekade terakhir, SPA dan aplikasi seluler yang tebal berinteraksi dengan server melalui API telah mendapatkan popularitas dan pengembangan yang luar biasa. Sebelumnya, pengembangan situs web interaktif dilakukan dengan pengeditan tahap demi tahap dari kode sisi-server untuk menghasilkan markup HTML dengan transfer berikutnya ke browser klien, tetapi sekarang pengembangan aplikasi web dinamis telah bergeser ke arah penciptaan API layanan tunggal dan pengembangan paralel dari banyak aplikasi (termasuk SPA) yang bekerja dengan API ini sebagai sumber data utama. Pendekatan ini memungkinkan Anda berbagi tugas dengan lebih mudah, mengatur tim yang hanya berspesialisasi dalam teknologi tertentu (menarik lebih banyak spesialis khusus), mengatur pengembangan paralel pada tahap pertama, dan juga memungkinkan Anda membuat satu titik komunikasi - antarmuka API.

Titik komunikasi semacam itu membutuhkan definisi formal dan tidak ambigu, dokumen ini adalah spesifikasi API. Untuk mengembangkan dan mendokumentasikan spesifikasi API hari ini, berbagai teknologi dan bahasa digunakan, misalnya: OAS (Swagger), Apiary dan RAML.

Tiga poin berikut menentukan sifat pendekatan pertama API:

  1. API harus menjadi antarmuka klien pertama dari aplikasi yang dikembangkan;
  2. Pertama-tama, spesifikasi API dikembangkan, dan kemudian bagian perangkat lunak kliennya;
  3. Tahap kehidupan dari suatu API harus bertepatan dengan tahap kehidupan dari dokumentasinya.

Jika kami mempertimbangkan proses berdasarkan hal tersebut di atas, maka spesifikasi API adalah pusat dari proses pengembangan, dan semua node yang membentuk sistem dan menggunakan API ini sebagai gateway interaksi adalah klien dari spesifikasi API. Dengan demikian, bagian server dari sistem dapat dianggap sebagai API spesifikasi klien yang sama, seperti simpul lain yang menggunakan API untuk berkomunikasi dengannya. Model domain aplikasi tidak harus cocok dengan model yang dijelaskan dalam spesifikasi API. Kemungkinan kebetulan yang disengaja dengan struktur kelas dalam kode aplikasi klien atau dengan struktur skema basis data diperkenalkan untuk menyederhanakan proses pengembangan, misalnya, ketika menggunakan generator kode sesuai dengan spesifikasi OAS. Logikanya, di atas dapat diringkas di bawah definisi kontrak tunggal . Kontrak tunggal - banyak klien.

Kontrak tunggal. Alat Kontrak dan Perpustakaan


Istilah Kontrak Tunggal tidak mengklaim partisipasi dalam kritik untuk penggunaannya dalam teks artikel. Penerapannya, dalam konteks ini, secara pribadi adalah ide saya.
Memperluas konsep API terlebih dahulu ke kontrak tunggal yang lebih umum memungkinkan kita untuk mempertimbangkan spesifikasi API tidak hanya sebagai deskripsi formal antarmuka antara komponen-komponen sistem, tetapi juga sebagai kontrak tunggal yang digunakan oleh sejumlah pustaka dan alat eksternal sebagai sumber konfigurasi. Dalam hal ini, alat dan perpustakaan ini dapat dianggap sebagai pelanggan kontrak bersama dengan SPA atau aplikasi seluler. Contoh klien tersebut termasuk:

  • Generator Dokumentasi
  • API mock-server
  • Layanan pengujian stres
  • Perpustakaan Validasi Permintaan / Tanggapan
  • Pembuat kode
  • Generator UI
  • dll.

Kontrak tunggal untuk klien tersebut adalah file konfigurasi tunggal dan sumber data. Instrumen kontrak hanya berfungsi berdasarkan informasi yang diperoleh dari kontrak tertentu. Jelas, untuk fungsionalitas penuh dari klien heterogen seperti API server tiruan, satu deskripsi API tidak cukup, meta-informasi tambahan diperlukan, misalnya, deskripsi hubungan antara parameter permintaan GET (id sumber daya) dan data yang harus dikembalikan oleh server, petunjuk yang menunjuk ke bidang respons dan parameter kueri yang digunakan untuk mengatur pagination. Selanjutnya contoh ini akan dipertimbangkan secara lebih rinci. Informasi spesifik untuk instrumen spesifik, pada saat yang sama, harus ada dan dipertahankan tanpa terpisahkan dari dokumen utama, jika tidak, ini akan melanggar konsep kontrak tunggal.

Sombong (OAS) sebagai Alat Deskripsi Kontrak Tunggal


Yang ada yang paling populer di pasar Swagger (OAS) dan Apiary (Blueprint) memungkinkan Anda untuk menggambarkan API HTTP menggunakan bahasa khusus: API Terbuka berdasarkan YAML atau JSON, Blueprint berdasarkan Markdown, yang membuat spesifikasinya mudah dibaca. Ada juga banyak alat dan perpustakaan yang dibuat oleh komunitas open-source yang besar. Swagger saat ini didistribusikan secara luas dan, bisa dikatakan, telah menjadi standar de facto API terlebih dahulu. Banyak sistem eksternal mendukung impor spesifikasi Swagger, seperti SoapUI , Readme.io , Apigee , dll. Selain itu, SaaS Swagger Hub dan Apiary yang ada memungkinkan pengguna untuk membuat proyek, mengunggah atau membuat spesifikasi sendiri, menggunakan generator dokumentasi dan server tiruan, serta menerbitkan tautan untuk mengaksesnya dari luar.

Menyombongkan diri dengan OAS 3.0 terlihat cukup percaya diri dan fungsinya untuk menggambarkan API (terutama sederhana) sudah cukup dalam banyak kasus. Berikut ini adalah daftar pro dan kontra dari Swagger:

Pro:

  • Bahasa deskripsi yang jelas dan mudah dibaca;
  • Komunitas open-source yang besar;
  • Banyak editor, generator, perpustakaan sumber dan resmi;
  • Kehadiran tim pengembangan inti secara konstan bekerja pada pengembangan dan peningkatan format;
  • Shareware hub untuk spesifikasi;
  • Dokumentasi resmi terperinci;
  • Ambang entri rendah.

Cons:

  • Dukungan modularitas yang lemah;
  • Kurangnya contoh respons kueri yang dihasilkan secara otomatis berdasarkan deskripsi strukturnya;
  • Sering ada masalah dengan stabilitas buruk dari produk SmartBear (penulis angkuh) dan reaksi terlambat dari pengembang untuk ini (pendapat didasarkan murni pada pengalaman penggunaan pribadi dan pengalaman tim kami).

Tetapi batasan utama yang tidak memungkinkan penggunaan OAS sebagai alat untuk menggambarkan kontrak tunggal adalah kurangnya kemampuan untuk melampirkan informasi meta khusus untuk menggambarkan parameter tambahan alat target / perpustakaan.
Oleh karena itu, semua alat yang bekerja berdasarkan spesifikasi Swagger harus puas dengan set informasi yang dapat mengakomodasi format dasar.

Misalnya, penerapan server api mock pintar memerlukan informasi lebih banyak daripada yang dapat disediakan oleh dokumen spesifikasi, itulah sebabnya built-in API Swagger Hub mock hanya mampu menghasilkan data palsu berdasarkan tipe / struktur data yang diperoleh dari dokumen spesifikasi. Tidak diragukan lagi, ini tidak cukup dan fungsi mock-server seperti itu hanya dapat dipenuhi oleh klien API sederhana.

Di perusahaan kami, selama pengembangan salah satu proyek (React SPA + API server), fungsionalitas server mock berikut diperlukan:

  • tiruan pagination. Server tidak boleh mengembalikan nilai acak sepenuhnya dari halaman saat ini, halaman berikutnya, halamanTotal dalam menanggapi permintaan daftar, tetapi dapat mensimulasikan perilaku nyata mekanisme pagination dengan generasi nilai metapole ini tergantung pada nilai halaman yang diterima dari klien;
  • menghasilkan badan tanggapan yang berisi berbagai set data tergantung pada parameter spesifik dari permintaan yang masuk;
  • kemampuan untuk membangun hubungan nyata antara objek palsu: bidang foo_id entitas Bar harus merujuk ke entitas Foo yang dibuat sebelumnya. Ini dapat dicapai dengan menambahkan dukungan idempotensi ke server tiruan;
  • tiruan karya berbagai metode otorisasi: OAuth2, JWT, dll.

Tanpa semua ini, sangat sulit untuk mengembangkan SPA secara paralel dengan pengembangan bagian server dari sistem. Dan, pada saat yang sama, server tiruan seperti itu, karena dijelaskan sebelumnya, hampir tidak mungkin untuk diimplementasikan tanpa tambahan informasi meta spesifik yang dapat disimpan secara langsung dalam spesifikasi API dan menginformasikannya tentang perilaku yang diperlukan ketika mensimulasikan titik akhir berikutnya. Masalah ini dapat diselesaikan dengan menambahkan parameter yang diperlukan dalam bentuk file terpisah dengan konfigurasi yang sejajar dengan spesifikasi OAS dasar, tetapi, dalam hal ini, Anda perlu mendukung dua sumber berbeda secara terpisah.

Jika akan ada lebih dari satu server tiruan dengan alat yang bekerja di lingkungan pengembangan sesuai dengan prinsip ini, maka kita akan mendapatkan “kebun binatang” alat, yang masing-masing, yang memiliki fungsi uniknya sendiri, terpaksa memiliki file konfigurasi sendiri yang unik, yang terhubung secara logis ke API dasar -spesifikasi, tetapi sebenarnya terletak secara terpisah dan menjalani "kehidupan mereka sendiri".

gambar

Masalah: pengembang akan dipaksa untuk mempertahankan relevansi semua konfigurasi setelah mengubah versi spesifikasi dasar, seringkali di tempat dan format yang sama sekali berbeda.

Beberapa contoh layanan yang bekerja dengan prinsip serupa:

  • SoapUI adalah sistem untuk menguji antarmuka REST & SOAP. Mendukung mengimpor proyek dari spesifikasi Swagger. Saat mengubah spesifikasi Swagger dasar, konfigurasi proyek berdasarkan daftar panggilan API terus ada secara paralel dan memerlukan sinkronisasi manual;
  • Produk SmartBear Lainnya;
  • Apigee adalah layanan manajemen siklus hidup API. Ia menggunakan spesifikasi Swagger sebagai templat, atas dasar yang memungkinkan untuk menginisialisasi konfigurasi layanan internal. Juga tidak ada sinkronisasi otomatis;
  • Readme.io adalah layanan yang memungkinkan Anda membuat dokumentasi yang indah berdasarkan spesifikasi Swagger, dan juga memiliki mekanisme untuk melacak perubahan pada spesifikasi dasar dan menyelesaikan konflik dengan memperbarui konfigurasi proyek di sisi layanan. Tentunya, ini membutuhkan kompleksitas yang tidak perlu dalam mengembangkan layanan ini.

Anda dapat menambahkan banyak layanan lain ke daftar ini yang menyediakan fungsi integrasi dengan spesifikasi Swagger. Integrasi untuk sebagian besar dari mereka berarti penyalinan biasa dari struktur dasar spesifikasi Swagger dan pelengkapan otomatis berikutnya dari bidang konfigurasi lokal tanpa mendukung sinkronisasi dengan perubahan pada spesifikasi dasar.

RAML, anotasi, overlay


Keinginan untuk menemukan alat yang mengecualikan pembatasan OAS yang disebutkan sebelumnya, memungkinkan kami untuk mempertimbangkan spesifikasi sebagai kontrak tunggal untuk semua alat klien, telah membuat kami menjadi terbiasa dengan bahasa RAML. Ada cukup banyak tulisan tentang RAML, Anda dapat membacanya, misalnya, di sini https://www.infoq.com/articles/power-of-raml . Pengembang RAML telah mencoba meletakkan dukungan bahasa untuk modularitas pada tingkat konsepnya. Sekarang setiap perusahaan atau pengembang individu dapat membuat sendiri atau menggunakan kamus publik yang siap pakai saat mendesain API, mendefinisikan kembali dan mewarisi model data yang sudah jadi. Dimulai dengan versi 1.0, RAML mendukung 5 jenis modul eksternal yang berbeda: termasuk, pustaka, ekstensi, sifat, overlay , yang memungkinkan masing-masing modul digunakan sefleksibel mungkin tergantung pada tugas.

Waktunya telah tiba untuk membahas kemungkinan utama RAML, yang, karena alasan yang tidak sepenuhnya dipahami, tidak memiliki analog dalam OAS dan Cetak Biru - Anotasi.
Anotasi dalam RAML adalah kemampuan untuk melampirkan metadata khusus ke struktur bahasa yang mendasarinya.
Fungsi RAML inilah yang menjadi alasan untuk menulis artikel ini.

Contoh:

#%RAML 1.0 title: Example API mediaType: application/json # Annotation types block may be placed into external file annotationTypes: validation-rules: description: | Describes strict validation rules for the model properties. Can be used by validation library allowedTargets: [ TypeDeclaration ] type: string[] info-tip: description: | Can be used by Documentation generator for showing tips allowedTargets: [ Method, DocumentationItem, TypeDeclaration ] type: string condition: description: | Named example can be returned if condition is evaluated to true. Can be used by Intelligent mock server allowedTargets: [ Example ] type: string types: Article: type: object properties: id: type: integer title: string paragraphs: Paragraph[] createdAt: type: string (validation-rules): ["regex:/\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d(?:\.\d+)?Z?/"] Paragraph: type: object properties: order: type: integer (validation-rules): ["min:0"] content: string (validation-rules): ["max-length:1024"] /articles/{articleId}: get: (info-tip): This endpoint is deprecated description: Returns Article object by ID responses: 200: body: application/json: type: Article

Struktur penjelasan pengguna sendiri harus memiliki deskripsi yang jelas dalam RAML. Untuk ini, bagian AnnotationTypes khusus digunakan, definisi yang juga dapat dibawa ke modul eksternal. Dengan demikian, menjadi mungkin untuk menetapkan parameter khusus alat eksternal dalam bentuk anotasi yang dilampirkan pada definisi dasar API RAML. Untuk menghindari kekacauan spesifikasi dasar dengan sejumlah besar anotasi untuk berbagai alat eksternal, ada dukungan untuk kemungkinan mentransfernya ke file terpisah - overlay (dan juga ekstensi ), dengan klasifikasi berdasarkan ruang lingkup. Inilah yang dikatakan tentang overlay dalam dokumentasi RAML ( https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#overlays ):
Overlay menambah atau menimpa node definisi API RAML sambil mempertahankan aspek perilaku dan fungsionalnya. Node tertentu dari definisi RAML API menentukan perilaku API: sumber dayanya, metode, parameter, badan, respons, dan sebagainya. Node ini tidak dapat diubah dengan menerapkan overlay. Sebaliknya, node lain, seperti deskripsi atau anotasi, mengatasi masalah di luar antarmuka fungsional, seperti dokumentasi deskriptif berorientasi manusia dalam beberapa bahasa, atau informasi implementasi atau verifikasi untuk digunakan dalam alat otomatis. Node-node ini dapat diubah dengan menerapkan overlay.

Overlay sangat penting untuk memisahkan antarmuka dari implementasi. Overlay memungkinkan siklus hidup terpisah untuk aspek perilaku API yang perlu dikontrol dengan ketat, seperti kontrak antara penyedia API dan konsumennya, versus yang membutuhkan sedikit kontrol, seperti aspek berorientasi manusia atau implementasi yang dapat berkembang pada langkah yang berbeda. Misalnya, menambahkan kait untuk alat pengujian dan pemantauan, menambahkan metadata yang relevan dengan registri API, atau menyediakan dokumentasi manusia yang diperbarui atau diterjemahkan dapat dicapai tanpa mengubah aspek aspek perilaku API. Hal-hal ini dapat dikontrol melalui versi yang ketat dan mengubah proses manajemen.
Dengan kata lain, fungsi ini memungkinkan Anda untuk "memisahkan biji-bijian dari sekam", misalnya, deskripsi utama spesifikasi API, dari meta-informasi tambahan khusus ke alat tertentu yang menggunakannya untuk pekerjaan. Meta-informasi dalam setiap overlay terpisah "digantung" pada berbagai blok spesifikasi dalam bentuk anotasi.

Contoh struktur dasar:

 #%RAML 1.0 title: Phrases API mediaType: application/json types: Phrase: type: object properties: content: string /phrases: get: queryParameters: whoSaid: string responses: 200: body: application/json: type: Phrase

Hamparan:
 #%RAML 1.0 Overlay usage: Applies annotations for Intelligent mock server extends: example_for_article_2_1.raml annotationTypes: condition: description: | Named example can be returned if condition is evaluated to true type: string allowedTargets: Example /phrases: get: responses: 200: body: application/json: examples: firstExample: (condition): $whoSaid is Hamlet content: "To be, or not to be?" secondExample: (condition): $whoSaid is Homer Simpson content: "D'oh!"

Akibatnya, menjadi mungkin untuk menerapkan kontrak tunggal: semua informasi fungsional, perilaku dan meta disimpan dan diversi dalam satu tempat, dan alat kontrak - klien kontrak, harus memiliki dukungan untuk anotasi yang digunakan dalam spesifikasi ini. Di sisi lain, itu adalah alat itu sendiri yang dapat menyajikan persyaratan mereka sendiri untuk anotasi, yang harus "digantung" pada spesifikasi - ini akan memberikan berbagai kemungkinan yang lebih luas ketika mengembangkan alat kontrak.

Konsep di atas digambarkan pada gambar di bawah ini:

gambar

Di antara kekurangan dari pendekatan ini, seseorang dapat memilih kompleksitas tinggi sinkronisasi manual dari file spesifikasi dasar dan masing-masing overlay: ketika memperbarui struktur spesifikasi dasar, Anda perlu menerapkan perubahan yang diperlukan dalam struktur overlay. Masalah ini menjadi lebih serius ketika lebih dari satu overlay muncul.

Solusi yang mungkin dan paling jelas adalah mengembangkan editor khusus atau tambahan untuk editor RAML online yang ada https://github.com/mulesoft/api-designer . Area pengeditan tetap tidak berubah, tetapi dimungkinkan untuk membuat tab: setiap tab baru adalah jendela untuk mengedit overlay yang ditetapkan untuk itu. Saat mengedit struktur dasar spesifikasi di jendela utama, struktur di semua tab yang dibuat juga berubah, dan ketika ketidakcocokan struktur baru dengan anotasi yang ada yang terletak di tab-overlay terdeteksi, peringatan akan muncul. Pertimbangan yang lebih rinci dari editor semacam itu adalah topik yang terpisah dan patut mendapat pertimbangan serius.

Perkembangan yang ada


Dalam mencari solusi yang ada yang dekat dengan mewujudkan gagasan menggunakan anotasi sebagai sarana menggambarkan meta-informasi, solusi berikut ditemukan:

  • https://github.com/raml-org/raml-annotations repositori yang berisi anotasi resmi yang disetujui oleh komunitas pengembang RAML. Dalam versi saat ini, hanya penjelasan OAuth2 yang tersedia. Mereka dapat digunakan oleh alat eksternal untuk mendapatkan meta-informasi yang menggambarkan aspek-aspek implementasi OAuth2 untuk spesifikasi API yang dikembangkan;
  • https://github.com/petrochenko-pavel-a/raml-annotations pustaka anotasi pengguna @ petrochenko-pavel-a dengan pengelompokan logis berdasarkan area aplikasi. Proyek ini lebih eksperimental, tetapi menggambarkan ide menggunakan anotasi dengan sempurna. Grup anotasi paling menarik:
    • additionalValidation.raml - anotasi untuk menjelaskan aturan tambahan untuk validasi model spesifikasi. Mereka dapat digunakan, misalnya, oleh perpustakaan server untuk memvalidasi permintaan sesuai dengan spesifikasi RAML;
    • mock.raml - penjelasan untuk mendeskripsikan detail server mock berdasarkan spesifikasi RAML;
    • semanticContexts.raml - anotasi yang menunjuk pada konteks semantik dari masing-masing blok struktural yang dinyatakan dari spesifikasi RAML;
    • structural.raml - penjelasan yang menjelaskan peran entitas RAML yang terpisah dalam struktur keseluruhan model domain yang dijelaskan;
    • uiCore.raml - contoh anotasi yang mungkin digunakan oleh perangkat generasi UI berdasarkan spesifikasi RAML;

Repositori juga berisi pustaka dari jenis utilitas yang cocok untuk digunakan sebagai primitif dalam menggambarkan struktur data spesifikasi RAML.

Masalah RAML


Terlepas dari fungsionalitas, progresif ide dasar, dan perhatian dari produsen perangkat lunak besar (cisco, spotify, vmware, dll.), RAML saat ini memiliki masalah serius yang dapat berakibat fatal sehubungan dengan nasib suksesnya:

  • Komunitas open-source kecil dan terfragmentasi;
  • Strategi yang tidak bisa dipahami dari pengembang RAML utama adalah mulesoft . Perusahaan mengembangkan produk yang hanya merupakan salinan dari solusi berbasis OAS yang ada (termasuk dalam Platform Anypoint ), alih-alih menciptakan layanan yang menekankan keunggulan RAML daripada Swagger;
  • Konsekuensi dari paragraf pertama: sejumlah kecil perpustakaan / alat sumber terbuka;
  • Ambang entri lebih tinggi daripada OAS (ini aneh, tetapi banyak orang berpikir demikian);
  • Karena banyaknya bug dan masalah dengan UX / UI, layanan utama yang benar-benar tidak cocok dan menolak pengguna adalah titik masuk ke RAML - https://anypoint.mulesoft.com/ .

Ketidaksetujuan konseptual. Kesimpulan pertama


Ada kontradiksi dalam komunitas mengenai konsep dasar. Seseorang berpikir bahwa RAML adalah bahasa definisi model , dan seseorang berpikir bahwa itu adalah bahasa definisi API seperti OAS atau Blueprint (orang yang menyebut diri mereka pengembang RAML sering menyebut ini dalam berbagai komentar). Konsep bahasa definisi model akan memungkinkan di dalam spesifikasi RAML untuk mendeskripsikan model domain dari domain tanpa ikatan yang erat dengan konteks deskripsi sumber daya API, dengan demikian memperluas cakrawala opsi untuk menggunakan spesifikasi dengan alat eksternal (pada kenyataannya, menciptakan fondasi untuk keberadaan kontrak tunggal ini!). Berikut adalah definisi konsep sumber daya yang dapat dilihat di situs web readhat docs ( http://restful-api-design.readthedocs.io/en/latest/resources.html , omong-omong, saya sarankan semua orang untuk membaca panduan hebat tentang desain API ini):
Kami menyebut informasi yang menjelaskan jenis sumber daya yang tersedia, perilaku mereka, dan hubungannya dengan model sumber daya API . Model sumber daya dapat dilihat sebagai pemetaan yang tenang dari model data aplikasi .
Dalam model data aplikasi RAML , ini adalah tipe yang dideklarasikan di blok tipe , dan model sumber daya dari API adalah apa yang dijelaskan dalam blok RAML sumber daya . Karena itu, Anda harus memiliki kemampuan untuk menggambarkan pemetaan ini. Tetapi implementasi RAML saat ini memungkinkan pemetaan seperti itu dilakukan hanya 1 banding 1, yaitu, untuk menggunakan jenis "apa adanya" di dalam deklarasi API sumber daya.

Saya pikir ini adalah masalah utama bahasa, solusi yang akan memungkinkan RAML melampaui bahasa definisi API dan menjadi bahasa definisi model yang lengkap: bahasa yang lebih umum (daripada OAS atau Cetak Biru) yang digunakan untuk menggambarkan kontrak tunggal sistem, yang pada dasarnya adalah inti formal banyak komponennya.

Hal di atas membuat RAML pemain yang lemah yang saat ini tidak dapat memenangkan persaingan melawan Swagger. Mungkin inilah sebabnya, pengembang utama RAML mengambil langkah drastis https://blogs.mulesoft.com/dev/api-dev/open-api-raml-better-together/

Gagasan SaaS RAML kontrak tunggal


Berdasarkan konsep kontrak Tunggal , mulai dari gagasan hosting spesifikasi API Swagger spesifikasi OAS berbasis OAS, serta mengandalkan kemungkinan RAML untuk mendeklarasikan informasi meta dan berbagi spesifikasi dasar menggunakan overlay, gagasan solusi SaaS alternatif untuk hosting dan mengelola spesifikasi berdasarkan bahasa RAML menyarankan Melampaui Swagger Hub dan Apiary dalam volume dan kualitas fungsionalitas yang memungkinkan.

Layanan baru, dengan analogi dengan hub Swagger, akan menjadi hosting kontrak pengguna dengan penyediaan editor online dan kemampuan untuk melihat pratinjau dokumentasi dengan pembaruan real-time. Perbedaan utama seharusnya adalah adanya katalog plug-in kontrak yang dibangun ke dalam layanan, di mana pengguna dapat menginstal spesifikasi API dalam proyeknya saat ini. Untuk instalasi, akan diperlukan untuk menerapkan anotasi RAML yang diperlukan yang ditentukan dalam dokumentasi plugin. Setelah menambahkan plug-in baru ke proyek, tab baru akan ditambahkan di jendela editor kode ketika Anda beralih ke sana, mengedit anotasi plug-in yang diinstal akan tersedia. Struktur spesifikasi dasar harus diduplikasi secara otomatis di semua tab yang sesuai dengan plugin. Jika konflik muncul antara struktur dasar dan anotasi yang sudah ada, mekanisme khusus harus menawarkan opsi untuk solusinya, atau menyelesaikannya secara otomatis.

gambar

Secara teknis, setiap tab akan menjadi abstraksi overlay RAML yang berisi anotasi dari setiap plugin tertentu. Ini memastikan bahwa spesifikasi tersebut kompatibel dengan alat apa pun yang mendukung RAML 1.0.

Direktori plugin harus terbuka untuk ekspansi oleh komunitas open source. Dimungkinkan juga untuk menerapkan plug-in berbayar, yang dapat berfungsi sebagai insentif untuk pengembangan yang baru.

Plugin yang mungkin: Dokumentasi API dengan dukungan untuk sejumlah besar anotasi untuk parameterisasi fleksibel dari renderingnya, server "pintar" (dari contoh di atas), perpustakaan yang dapat diunduh untuk memvalidasi permintaan atau pembuatan kode, alat debugging untuk permintaan API keluar untuk aplikasi mobile (caching proxy), uji beban dengan pengaturan pengujian aliran melalui anotasi, berbagai plugin untuk integrasi dengan layanan eksternal.

Gagasan layanan ini mengandung keunggulan yang jelas dibandingkan layanan yang ada untuk mengelola spesifikasi API, dan implementasinya membuka jalan bagi kemungkinan perubahan dalam pendekatan untuk penerapan sistem eksternal apa pun yang entah bagaimana terkait dengan API.

Kesimpulan kedua


Tujuan artikel ini bukan untuk mengkritik Swagger, Apiary, atau alat standar de facto lainnya untuk mengembangkan API, melainkan untuk menguji perbedaan konseptual dengan pendekatan spesifikasi desain yang dipromosikan oleh RAML, berusaha memperkenalkan konsep Kontrak terlebih dahulu dan mempertimbangkan kemungkinan penerapannya berdasarkan RAML. Tujuan lain adalah keinginan untuk menarik perhatian pengembang yang layak ke RAML untuk pengembangan lebih lanjut dari komunitasnya.

RAML situs resmi
Saluran kendur
Spesifikasi

Terima kasih atas perhatian anda

Source: https://habr.com/ru/post/id419525/

More articles:


All Articles