🤰🏼 🐡 🕓 Tentukan. Laporan Yandex 🐀 🥘 🍹

Spesifikasi API yang baik membantu pelanggan menggunakannya. Beberapa bulan yang lalu di Big Pytup, pengembang Yandex Alexander Bryazginbryazginnnmembuat presentasi tentang apa yang berdasarkan spesifikasi REST API sebagai contoh OpenAPI + Swagger dan mengapa bundel seperti itu diperlukan. Dari sinopsis Anda dapat mengetahui bagaimana kami mengacaukan pembuatan otomatis spesifikasi dalam layanan yang sudah jadi, perpustakaan mana yang berguna bagi kami dan jenis tuning apa yang ada di sekitar spesifikasi OpenAPI.

- Halo semuanya, nama saya Alexander. Saya ingin berbicara dengan Anda tentang spesifikasinya.

Secara khusus, saya ingin menyentuh beberapa topik. Pertama-tama, apa spesifikasi menggunakan contoh spesifikasi API REST. Lebih lanjut - saat kami memasang generasi spesifikasi dalam layanan kami. Dan pada akhirnya, di sisi manis - alat apa, tuning, untuk menggunakan hasil generasi spesifikasi kami, pada contoh spesifikasi seperti OpenAPI dan Swagger UI.

Spesifikasi API SISA

Apa spesifikasi dan apa yang saya maksud dengan ini dalam laporan saya?

Pertama-tama, itu adalah Deskripsi Antarmuka Bahasa, bahasa untuk menggambarkan antarmuka, beberapa deskripsi yang sesuai dengan format tertentu. Ini dapat diuraikan secara otomatis, karena memiliki format yang ketat dan spesifik sehingga tidak tergantung pada bahasa itu sendiri di mana antarmuka diimplementasikan. Artinya, katakanlah Anda memiliki server web Python, untuk Bahasa Deskripsi Antarmuka tidak masalah.

Ada banyak bahasa untuk menentukan spesifikasi. Ini adalah spesifikasi untuk REST, RPC, GraphQL, dll. Hari ini kita akan membahas spesifikasi REST.

Openapi

Mari kita bicara tentang spesifikasi menggunakan contoh OpenAPI.

Pertama, mari kita pahami apa itu OpenAPI. Ini hanya bahasa yang sama untuk menggambarkan spesifikasi. Dengan sendirinya, itu adalah file - dalam format YAML, JSON atau XML, siapa pun yang lebih menyukainya - dengan deskripsi antarmuka, pegangan-titik akhir dan skema.

Kesombongan

Ketika kami berbicara tentang OpenAPI, kami tidak dapat mengatakan tentang Swagger.

Swagger pada dasarnya adalah OpenAPI UI yang memungkinkan Anda memvisualisasikan spesifikasi Anda dengan indah.

Di Swagger, seperti pada OpenAPI, ada deskripsi titik akhir yang ada dalam spesifikasi Anda.

Ada deskripsi otorisasi di API Anda.

Ada deskripsi model atau sirkuit yang Anda manipulasi di API Anda - misalnya, terima untuk input atau kembalikan untuk output.

Ada deskripsi contoh dan permintaan yang diharapkan dan tanggapan dari API Anda.

Dan juga di Swagger Anda, karena fakta bahwa itu adalah UI dan sedang berjalan di browser Anda, Anda dapat secara real time mengeksekusi permintaan ke API Anda di sini dan sekarang.

^{_{Tautan dari slide}}

Dengan semua ini, Anda dapat bermain-main di bangku tes yang disiapkan oleh tim Swagger. Ini adalah petstore.swagger.io. Ada contoh spesifikasi, yang diangkat oleh Swagger. Anda dapat pergi ke backend nyata dan menyentuh. Sarankan.

Jadi, kita katakan: OpenAPI, Swagger, spesifikasi. Tetapi mengapa semua ini diperlukan bagi orang yang menulis, katakanlah, backend?

Pertama-tama, spesifikasi sering digunakan selama fase desain API kami. Artinya, orang normal, setelah sampai pada tugas menulis backend, mulai dengan menggambarkan apa yang ingin mereka terapkan. Artinya, mereka mulai merancang API mereka, daftar titik akhir yang ingin mereka implementasikan, daftar skema yang akan dimanipulasi, parameter, dll. Dalam hal ini, spesifikasi dan alat di sekitar spesifikasi sangat nyaman.

Selain itu, ada kasus yang populer. Demi apa kami menyeret spesifikasi kepada kami dalam pelayanan? Ini dokumentasinya. Ketersediaan spesifikasi memberi Anda peluang bagus untuk menggambarkan API dan membagikan informasi ini dengan seseorang: baik dengan vendor front-end di tim Anda, atau dengan klien eksternal yang ingin berintegrasi dengan Anda.

Juga, karena fakta bahwa spesifikasi ditulis dalam format ketat tertentu, maka dapat diproses secara otomatis, yaitu, terlibat dalam introspeksi API. Dan di atas Anda dapat menangkap banyak alat yang dapat membuat hidup Anda lebih mudah. Saya akan memberi tahu Anda lebih spesifik dan lebih detail nanti.

Bagaimana kami mempersiapkan OpenAPI

Kami memutuskan mengapa kami membutuhkan semua ini. Mari kita bicara tentang bagaimana kita mengacaukan pembuatan spesifikasi dalam layanan kami. Pertama, sedikit konteks.

Ketika kami sampai pada kesimpulan bahwa kami akan memotong spesifikasi, kami tidak mengikuti jalur normal ketika kami pertama kali menulis proyek, dalam arti prototipe dengan spesifikasi. Kami sudah mengangkat beberapa backend, itu sudah terbang bersama kami, dan kami ingin berbagi spesifikasi sebagai cara mendokumentasikan.

Dan backend kami tiba-tiba menggunakan Python. Kami menggunakan Falcon sebagai kerangka kerja, marshmallow sebagai alat serialisasi dan deserialisasi, dan webargs sebagai alat validasi.

Menggunakan kliping paling sederhana dari petstore yang saya sebutkan sebelumnya, kami akan membayangkan bagaimana layanan kami akan terlihat pada tahap ketika kami ingin menghasilkan spesifikasi.

Dalam layanan kami, akan ada sepasang skema yang disederhanakan: jenis hewan peliharaan kami, yaitu, kategori, dan, pada kenyataannya, hewan itu sendiri.

Yaitu, kami akan menjelaskan beberapa skema di Marshmallow. Selanjutnya, kami akan menyiapkan beberapa pena untuk, misalnya, untuk mendaftar dan menerima favorit kami.

Dan, pada kenyataannya, mereka akan menggambarkan aplikasi itu sendiri, yang akan meningkatkan titik akhir untuk membuat dan menerima hewan peliharaan.

Inilah yang akan terlihat bersama. Layanan yang cukup sederhana.

Mari kita pikirkan opsi apa yang kita miliki untuk membuat konfigurasi OpenAPI. Opsi paling sederhana dan paling naif, seperti yang saya katakan sebelumnya, hanyalah sebuah file. Mengapa kita tidak membuat file ini dengan tangan kita? Kami tahu apa input data yang kami miliki, kami memiliki titik akhir. Tampak jelas, ambil dan tulis saja.

Tapi pertama-tama, kita adalah programmer. Kami tidak suka melakukan apa pun dengan tangan kami. Kami ingin sesuatu standar dihasilkan untuk kami. Kedua, jika kami mendukung semuanya dengan tangan, kami tentu harus mendukung perubahan API, serta file yang terletak di tempat lain. Seperti halnya layanan apa pun, produk kami mudah berubah, demikian juga spesifikasinya.

Oleh karena itu, kami sampai pada kesimpulan bahwa kami ingin membuat konfigurasi OpenAPI. Mengingat tumpukan teknologi kami, kami menemukan perpustakaan seperti apispec . Apispec adalah perpustakaan dari produsen, yaitu penulis Marshmallow dan Webargs. Bersama-sama mereka membentuk ekosistem besar.

Mari kita lihat bagaimana Anda dapat menggunakan apispec pada tumpukan kami untuk mengajarkannya cara membuat spesifikasi untuk kami.

Kami memiliki sumber daya dan penangan khusus untuk mendapatkan metode sumber daya ini. Dia punya semacam tubuh.

Untuk mengajar apispec, agar dia tahu apa yang kita lakukan dengan pena kita, kita menambahkan sesuatu ke docstring. Kami menambahkan deskripsi di sana yang dapat dimengerti oleh manusia. Dalam kasus kami, ini adalah contoh jawaban: kadang-kadang itu terjadi, pena kami menjawab dengan dua ratus, dan di tubuh jawaban kami ada JSON dengan skema, model data Pet.

Dengan menggunakan contoh post-request, kami menggambarkan: selain fakta bahwa ada respons 201 di mana kami mengembalikan Pet, ada juga badan permintaan yang diharapkan yang datang kepada kami. Dan di dalam permintaan ini, kami mengharapkan JSON, dan berharap JSON ini akan dalam format Pet.

Kami menambahkan dokumen, maka kami perlu belajar cara membuat spesifikasi. Untuk melakukan ini, kami menulis semacam naskah, tombol merah, dan mengajarkan apispec untuk menghasilkan spesifikasi bagi kami. Kami mendeklarasikan objek apispec, dari mana kami menggambarkan beberapa metadata layanan kami, dan kemudian kami hanya menulis file, spesifikasi yang dihasilkan dalam format YAML.

Mari kita lihat apa yang dihasilkan untuk aplikasi besar ini dalam file ini.

Pertama-tama, dalam file ini akan ada deskripsi versi di mana spesifikasi dihasilkan. Ini penting agar setiap orang yang menginterpretasikan spesifikasi ini memahami format mana yang ditafsirkan. Spesifikasi bervariasi dari versi ke versi.

Selanjutnya ada deskripsi layanan kami. Judul, versi ini, mungkin akan ada deskripsi, jika Anda menginginkannya, dan kemudian daftar server yang dapat Anda kunjungi, tarik pena, lihat dan sentuh backend kami.

Selain itu, skema data itu sendiri yang kami manipulasi sprout di sana, dengan deskripsi jenis, dengan contoh mengisi data ini dan beberapa aturan. Mungkin ini adalah beberapa nilai ekstrem, mungkin parameter yang mengikat. Di sini Anda melihat daftar atribut yang diperlukan.

Selain skema, deskripsi titik akhir sendiri tumbuh di sana. Dalam hal ini, deskripsi masing-masing metode kecambah.

Menggunakan metode get, kami mendapatkan deskripsi tentang apa yang kami lakukan dengan metode get.

Dan persis deskripsi yang kami masukkan dalam dokumen titik akhir yang sesuai tumbuh di pos. Artinya, kami telah menerima beberapa jenis file.

Apa yang akan kita lakukan dengan itu sekarang? Apa gunanya Pertama-tama, Anda, sebagai pemilik backend, sudah dapat memberikan semua pelanggan potensial ini yang akan pergi ke pena Anda, berikan spesifikasi ini. Dan ini akan membantu orang-orang berintegrasi. Artinya, file yang kami buat tidak membuat Anda mencungkil mata Anda. Cukup mudah dibaca. Itu bisa dilihat melalui mata dan entah bagaimana diurai.

Tetapi ini juga sulit. Mari kita lihat alat apa yang ada untuk menyederhanakan hidup Anda dan jenis tuning apa yang ada di sekitar spesifikasi yang dihasilkan.

Roti

Dan kemudian kita sampai pada tahap berikutnya, di mana kita akan berbicara tentang apa itu toolkit yang berguna seputar spesifikasi menggunakan contoh OpenAPI.

^{_{Tautan dari slide}}

Alat pertama yang ingin saya bicarakan adalah Swagger-UI. Selanjutnya, saya akan memberikan tautan ke sumber daya web tempat Anda dapat menyodok alat yang sesuai, dalam hal ini SwaggerHub, atau ke perintah untuk meluncurkan dokumen terkait menggunakan Docker.

Kita semua sangat mencintai Docker. Docker membantu Anda untuk tidak menempatkan JavaScript atau Java di lokal. Ambillah, jalankan dengan satu perintah, dan semuanya bekerja untuk Anda.

Jadi, Swagger-UI sebenarnya adalah sebuah utilitas yang memungkinkan Anda untuk menampilkan spesifikasi Anda dengan indah. Seperti yang saya katakan sebelumnya, ini berjalan secara lokal menggunakan Docker, mungkin Swagger.

Anda dapat melihat atau berbagi di lokal dengan menjalankan spesifikasi di Swagger pada perangkat keras Anda. Dan selanjutnya kirim semua pengguna potensial Anda ke spesifikasi ini. Dia sudah jauh lebih bisa dimengerti, cantik. Langsung di dalamnya, Anda bisa melakukan eksekusi query.

^{_{Tautan dari slide}}

Selain Swagger-UI, ada alat Swagger-editor yang nyaman. Anda dapat menggunakannya di web, Anda dapat mengambilnya di lokal atau di mesin tik apa pun. Ini memungkinkan Anda untuk mengubah spesifikasi secara waktu nyata dan melihat tampilannya di sini. Artinya, ini adalah alat yang sangat nyaman pada tahap, katakanlah, merancang API, ketika Anda tidak memiliki spesifikasi yang dihasilkan, dan Anda ingin entah bagaimana mengerjai atau menggambarkan backend Anda tanpa memiliki backend yang nyata atau dihasilkan di belakang.

Selanjutnya adalah alat Prisma yang luar biasa. Saya ingin membahasnya lebih detail. Prism adalah utilitas dari Spotlight. Ini memungkinkan Anda, dengan spesifikasinya, untuk meningkatkan mock-server, yang akan bekerja sesuai dengan spesifikasi yang Anda berikan kepadanya.

Artinya, dalam hal ini, kita melihat peluncuran Prism di atas spesifikasi, yang saya curi hanya dari bawah toko Swagger. Kita melihat bahwa Prism menemukan semua titik akhir yang ditentukan dalam spesifikasi, dan mengatakan bahwa mereka dengan jujur mengganggu mereka.

Mari kita coba rasakan apa yang bisa dilakukan Prism.

Pertama-tama, kami menemukan pena, mencoba menariknya dan tiba-tiba kami melihat Prism memberitahu kami: maaf, 401 kesalahan. Kami masuk ke spesifikasi dan melihat bahwa sebenarnya pena ini tersembunyi di balik otorisasi. Bagian keamanan dijelaskan dengan jelas di sana. Di dalamnya, kita melihat bahwa metode otorisasi adalah OAuth, dan kami memahami: pada kenyataannya, Prism mengharapkan beberapa jenis data otorisasi dari kami.

Mari kita coba mentransfer data otorisasi kepadanya sesuai dengan format yang dia tunggu. Jelas bahwa tokennya entah bagaimana lapang, karena Prism tidak peduli apa intinya. Format itu penting baginya. Artinya, jika dia menunggu OAuth, dia sedang menunggu data otorisasi dalam format tertentu.

Kami brengsek dengan Otorisasi dan sudah melihat kesalahan ke-400. Kami melihat apa yang kami miliki dalam spesifikasi. Dalam spesifikasi, kami melihat bahwa kami tidak melewati beberapa atribut yang diperlukan. Mari kita sampaikan.

Atribut ajaib adalah status. Itu, pada kenyataannya, diberikan sesuai dengan spesifikasi ENUM. Jika kami mentransfer status yang tidak termasuk dalam ENUM ini, kami akan mendapat empat titik.

Di sini kami melewati status yang valid dan kami melihat bahwa backend merespons dengan xml yang benar-benar valid dengan data. Data dalam xml ini sekarang hanya dikembalikan dari contoh yang ditentukan dalam spesifikasi. Yaitu, dalam spesifikasi untuk setiap bidang ada bagian seperti contoh, di mana Anda dapat menentukan contoh data yang mungkin kembali. Di sini Prism baru saja membawa mereka kembali.

Tetapi selain fakta bahwa Anda dapat menarik pena dan berharap bahwa akan ada dua ratus jujur, ada kesempatan untuk mengatakan Prism - kembalikan saya kode respons tertentu. Biasanya dalam spesifikasi kami menggambarkan perilaku pena kami yang berbeda, dan dengan data yang valid mereka tidak selalu sesuai dengan dua ratus. Mereka dapat mencari, misalnya, untuk keberadaan ID dalam database, untuk melihat bahwa ID tersebut tidak ada.

Untuk kasus ini, kami mendeklarasikan kode tertentu, katakanlah, yang ke-400 atau ke-422, kepada siapa saja yang Anda mau. Artinya, dengan entri yang valid, tidak selalu ada jalan keluar yang valid. Oleh karena itu, dalam spesifikasi, kami menjelaskan berbagai opsi jawaban. Dan kita dapat dengan jelas mengatakan ketika menyentak pena Prism: kali ini saya menunggu Anda untuk menjawab saya, katakanlah, kesalahan ke-404. Katakanlah ini adalah kasus ketika saya menarik pegangan dengan ID, tetapi tidak ada ID seperti itu.

Untuk meringkas, apa saja fitur secara umum, selain yang telah saya sebutkan? Sekali lagi, ini adalah server tiruan yang dapat Anda ambil. Dia akan merespons sesuai dengan spesifikasi, memvalidasi permintaan otorisasi. Itu juga akan memvalidasi pada data yang Anda kirim.

Selain memvalidasi permintaan, itu akan menghasilkan respons. Dalam kasus paling sederhana, seperti yang saya katakan, itu menghasilkan jawaban dengan contoh. Ada opsi kedua - ketika Anda memintanya secara eksplisit: harap buat jawaban dinamis. Strategi yang dinamis berarti bahwa, tergantung pada jenisnya, katakanlah, int, itu akan menghasilkan ribuan, milyaran, atau yang lainnya. Atau untuk string, hash yang aneh dan tidak bisa dipahami.

Juga, ketika saya mengatakan pada jalankan pertama bahwa Anda dapat menghasilkan data, kami bertanya pada diri sendiri: akan lebih baik jika Prism terintegrasi dengan faker. Mereka yang menggunakan pembuat Python mungkin tahu betapa kerennya ketika Anda ingin mengunci beberapa data atau mengemulasi data dalam database.

Jadi, Prism ditulis dalam JavaScript. JavaScript juga memiliki Faker.js, dan Prism memiliki integrasi otomatis dengan faker. Anda dapat secara eksplisit menentukan dalam spesifikasi Anda jenis data pemalsu yang akan diberikan pena Anda. Yaitu, OpenAPI mendukung sistem plug-in yang memungkinkan Anda untuk memperluas spesifikasi Anda sehingga OpenAPI dan pengurai itu sendiri tidak peduli. Tetapi jika ada plugin yang menguraikan spesifikasi Anda, mereka dapat menggunakan beberapa bidang tambahan.

Jadi, Prism menawarkan Anda untuk menggunakan bidang plugin X-faker opsional. Sangat nyaman.

Di sini, di bawah tanda bintang, saya menunjukkan bahwa panggilan balik dapat dijelaskan dalam OpenAPI. Ini adalah skema interaksi ketika Anda mendaftarkan panggilan balik ke pena tertentu dan menunggu untuk itu setelah itu Anda akan menerima panggilan balik khusus ke url yang Anda daftarkan. Jadi, Prism dan ia tahu cara basah.

Dari menarik: Prisma dapat dinaikkan tidak hanya dalam mode mock, tetapi juga dalam mode Proxy. Anda cukup meletakkan Proxy ini di depan backend asli Anda, dan semua permintaan yang melewati Prism dan kembali, Prism akan divalidasi sesuai spesifikasi.

Jika beberapa data - katakanlah, input atau output, permintaan atau respons - akan berbeda, ia akan menulis ini dalam log. Dia melakukan ini dengan cukup transparan, itu tidak mempengaruhi perilaku nyata. Secara umum, dokumentasi mengatakan bahwa itu dapat dengan mudah diangkat dalam produksi. Jujur, saya belum mencobanya sendiri. Tentunya ada semacam overhead, tapi saya masih belum bisa mengatakannya. Anda dapat merasakan, mencoba dan memberi tahu.

Selanjutnya, melalui apa yang telah saya katakan, adalah mungkin untuk memaksakan permintaan tertentu. Yaitu, datanglah ke server tiruan dan katakan: Saya ingin contoh atau tipe respons tertentu. Kami sudah bicara tentang jenis jawaban. Juga dalam spesifikasi OpenAPI dimungkinkan untuk menentukan beberapa opsi jawaban dan menamainya secara eksplisit.

Jadi, Anda bisa datang dan mengatakan Prism: kali ini saya ingin contoh spesifik, lain kali saya ingin contoh lain.

^{_{Tautan dari slide}}

Tentang Prism berbicara. Sekarang tentang tukang pos. Aku sangat mencintainya. Jadi, Postman memiliki integrasi di luar kotak dengan OpenAPI. Anda benar-benar dapat mengimpor spesifikasi OpenAPI hanya dengan dua klik tombol. Dan dia akan membuat koleksi permintaan sesuai dengan spesifikasi Anda.

Pada saat yang sama, ia akan melakukan pra-persiapan semua parameter kueri, semua parameter tubuh, semua lingkungan, dan otorisasi. Anda hanya perlu menyelesaikan data dengan beberapa ID asli atau sesuatu yang lain, token otorisasi. Sangat nyaman.

Kami lulus dari tukang pos lebih lanjut. Kami berbicara tentang Prism, ia memiliki fungsionalitas - validasi permintaan. Bahkan, ada utilitas terpisah yang memungkinkan Anda menyedot backend yang benar-benar berjalan tanpa ampun dan melihat apakah itu benar-benar berfungsi sesuai dengan spesifikasi.

Dredd mem-parsing spesifikasi. Dia mengambil, menarik semua pena dan melihat apa yang telah kembali padanya. Secara umum, dredd dapat diperlakukan sebagai infrastruktur untuk tes menulis, karena semua permintaannya dapat dilengkapi dengan kaitnya. Yaitu, dari kotak, Anda dapat memulai Dredd apa adanya, seperti yang saya luncurkan di sini.

Atau Anda dapat menjalankan dredd dengan melewatkannya satu set kait yang benar-benar berfungsi dalam ideologi tes reguler. Ada sesuatu yang naik ke seluruh rangkaian tes, ada kait yang berjalan sebelum tes, setelah tes, seluruh infrastruktur.

^{_{Tautan dari slide}}

Selanjutnya saya ingin berbicara lebih detail tentang alat dari Swagger itu sendiri sebagai Swagger-codegen. Bahkan, ini agak seperti pisau Swiss. Pertama-tama, pemikiran seperti apa yang dimiliki para lelaki ketika mereka menulis instrumen ini.

Biasanya, ketika seseorang perlu berintegrasi dengan backend, Anda jarang menggambarkan permintaan http di sini, pada tahap tertentu, dalam logika bisnis. Paling sering Anda merangkum kerja dengan backend tertentu di beberapa entitas, di klien.

Jadi, orang-orang datang dengan gagasan bahwa, memiliki spesifikasi, kita dapat dengan jelas menggambarkan dan memprediksi seperti apa klien untuk backend ini. Dan orang-orang membuat generator pelanggan.

Mari kita mulai generasi klien sesuai dengan spesifikasi toko. Kita akan melihat bahwa generator ini dihasilkan oleh klien Swagger itu sendiri, di mana ada klien Python itu sendiri. Di sini, di baris peluncuran Anda dapat dengan jelas melihat bahwa saya menghasilkan klien dengan Python. Bahkan, ia mendukung sejumlah besar bahasa. Apa yang penting di sini? Pelari depan akan menyukai JavaScript, hipsters akan suka Go. Semua yang kamu inginkan.

Jadi, selain klien dengan Python, ia membuat beberapa dokumen dan menguji folder ajaib. Kami akan membicarakannya nanti secara lebih rinci. Dan banyak gula sehingga Anda bisa membungkus klien ini di perpustakaan yang sudah jadi. Ada gitignore, ada file CI, katakanlah untuk Travis, ada gula untuk git. Ada persyaratan, setup.py dan tox.ini. Artinya, segala sesuatu yang membantu Anda hanya mengambil, mengkomit dan mengirim klien ini sudah dalam bentuk perpustakaan yang dapat digunakan kembali.

Mari kita lihat lebih dekat apa yang ia hasilkan di klien.

Di klien, ia menghasilkan, di samping beberapa file tambahan, dua direktori dan model yang sangat penting. Dalam model, kami memiliki model data yang kami manipulasi. Setiap model hanyalah sebuah kelas Python, yang diwarisi dari objek dengan __init__, yang mengambil semua jenis parameter untuk skema ini, dan getter dan setter yang mengubah keadaan objek.

Selain model, entitas seperti PetApi juga muncul di sana - ini hanya pembungkus klien di atas grup titik akhir, yang OpenAPI mengelompokkannya dengan tag atau titik akhir.

Dan klien ini memiliki semua pena yang dapat Anda sentangkan, mentransmisikan data nyata. Kemudian mereka akan terbang ke backend.

Apa yang diterapkan dari klien yang dihasilkan ini? Dari yang menarik - pendekatan kontrak. Mari kita bicara lebih banyak tentang dia.

Pendekatan kontraktual untuk pemrograman menyarankan bahwa ketika Anda mengimplementasikan interaksi antara klien dan server, Anda selalu selalu meletakkan aturan tertentu, pada kontrak, apakah itu data yang diberikan klien ke server, atau data yang diberikan server kepada klien.

Jadi, pendekatan kontrak merekomendasikan Anda untuk memeriksa data dan interaksi Anda untuk kepatuhan dengan kontrak setiap saat secara real time. Jika kontrak ini adalah skema data yang kami kirimkan, dan tidak memenuhi harapan kami, tidak puas, maka Anda perlu mengatakan ini, tunjukkan kesalahan di sini dan sekarang. Jangan pergi ke backend nyata, jangan menunggu empat titik, tetapi katakan sekarang.

Atau kasus lain: kami pergi ke backend, menerima beberapa data, tetapi mereka tidak sesuai dengan apa yang kami tunggu. Misalkan beberapa bidang yang kita harapkan sudah terisi kosong. Kami akan membicarakannya di sini dan sekarang, dan tidak ketika kami meninggalkan suatu tempat di tumpukan panggilan di suatu tempat di hutan dan tidak mencari tahu mengapa ada sesuatu yang jatuh.

Jadi, Swagger-codegen menghasilkan klien dan model sesuai dengan pendekatan kontrak. Ini memungkinkan Anda untuk mengatakan secara real time: ya, saya ingin klien di runtime memeriksa semua data untuk kesesuaian dengan kontrak. Dan jika kontraknya tidak terpenuhi, ia akan segera mengatakannya.

Kami menghasilkan semacam klien-pit dengan pendekatan kontrak, tetapi selain itu, Swagger-codegen menghasilkan stub dokumentasi untuk kami. Sebenarnya, mereka cukup sederhana, tetapi mereka semua dapat diputar untuk setiap model.

Juga Swagger-codegen menghasilkan semacam tes bertopik. Semuanya sehingga Anda dapat meluncurkan kode yang dihasilkan dengan upaya minimal dan menjalankannya dengan tes, dengan Continuous Integration, dalam bentuk perpustakaan dengan git, dengan semua lonceng dan peluit.

Mari kita lewati sebentar lagi. Kami hanya melihat satu kasus - cara untuk menghasilkan klien untuk API. Dari pendekatan kontrak} yang penting. Saya ingin mengatakan: ketika saya menghasilkan klien untuk petstore nyata sesuai dengan spesifikasi mereka dan benar-benar pergi ke backend mereka, kemudian tiba-tiba pendekatan kontrak ini menangkap data yang tidak valid yang dikembalikan oleh petstore.

Awalnya saya pikir - mereka agak aneh. Mereka sendiri menghasilkan spesifikasi, dan backend tidak berfungsi dengan benar untuk mereka. Tapi menurut saya mereka sengaja melakukannya sehingga kita bisa melihat kekuatan pendekatan kontrak. Tidak banyak data, dan mereka jelas dihasilkan.

Juga dalam generasi pelanggan dan generasi lain, Anda dapat menggunakan templat Anda sendiri. Artinya, jika Anda ingin menghasilkan klien dalam format tertentu, Anda dapat menyimpan dan menyiapkan template Anda dan menghasilkan klien seperti yang Anda inginkan. Jika Anda berkeliling dan menghasilkan integrasi setiap hari, Anda mungkin sangat menyukainya.

Anda juga dapat mengkonfigurasi klien ini dan menulis impor model Anda, daripada yang dihasilkan oleh Swagger-codegen.

Selain menghasilkan klien untuk API, Anda dapat memberi makan spesifikasi ke generator dan menghasilkan potongan dari server itu sendiri. Ini sangat aneh. Artinya, Anda menghasilkan semacam backend yang seharusnya bekerja sesuai dengan spesifikasi. Jelas bahwa tidak ada logika bisnis di sana. Tapi mungkin akan lebih mudah karena semacam perancah, yaitu, menyiapkan konsep yang dengannya Anda sudah bisa melakukan sesuatu. Saya belum menggunakannya, tapi saya sarankan untuk melihatnya - mungkin Anda akan menemukan sesuatu yang berguna untuk diri Anda sendiri.

Antara lain, itu memungkinkan Anda untuk menghasilkan dokumentasi dalam format HTML dan Confluence jika seseorang menggunakannya. Contoh yang ingin saya tunjukkan untuk OpenAPI juga berakhir di sana.

^{_{Semua alat ini tersedia di dua tautan di bawah ini pada slide: openapi.tools dangithub.com/APIs-guru/awesome-openapi3}}

Saya ingin menunjukkan grup tuning di sekitar spesifikasi OpenAPI. Sebenarnya, ada banyak alat. Ini hanya grup, yaitu jenis alat yang dapat Anda gunakan.

Yang terpenting di sini adalah konverter dari satu spesifikasi ke spesifikasi lainnya. Artinya, Anda dapat membuat Blueprint API atau apa pun yang Anda suka dari spesifikasi OpenAPI, dan sebaliknya. Ada perpustakaan untuk mock, untuk dokumentasi. Artinya, semua yang saya bicarakan akan tercermin dalam kelompok-kelompok ini.

Ada tautan yang bisa Anda ikuti juga. Pastikan untuk melihat.

^{_{Tautan dari slide}}

Selain alat-alat di sekitar OpenAPI, ada alat-alat di sekitar Swagger. Ada SwaggerHub dan Inspektur Swagger. Mereka disorot dengan warna biru karena ini adalah toolkit berbasis web. Anda dapat pergi langsung ke sana dan sebagai layanan gunakan SwaggerHub dan Inspektur Swagger, yang sebenarnya merupakan superposisi dari pustaka berikut: Swagger-codegen, Swagger-codegen, Swagger-UI. Semua itu baru saja kita bahas.

Semua perpustakaan berwarna kuning, mereka adalah open source, seperti yang kita lihat. Ada di GitHub, ada dalam bentuk Docker. Menggunakan.

Kesimpulan

Apa yang kita diskusikan hari ini? Spesifikasi REST API menggunakan OpenAPI dan Swagger sebagai contoh. Saya ingin menekankan bahwa OpenAPI hanyalah salah satu cara untuk menggambarkan spesifikasinya. Kebanyakan dari mereka. Dari tampilan menarik masih Blueprint API. Mungkin orang lain akan menyukai sesuatu.

Kami juga menyaksikan Swagger. Intinya, ini, seperti yang telah kami katakan, hanya UI yang indah di sekitar spesifikasi, yang memungkinkan Anda untuk melihat dan menjelajahinya dengan cara yang nyaman. Bahkan, alat ini juga banyak, mulai dari ReDoc dan Sphinx yang populer, dan berakhir, pada kenyataannya, Markdown. Artinya, Anda dapat membuat Markdown dari OpenAPI, dan itu akan ditampilkan dengan indah di semua GitHub, GitLab - di mana pun Anda inginkan.

Kami juga melihat contoh pada tumpukan teknologi kami bagaimana kami sekarang menghasilkan spesifikasi. Tetapi seperti yang Anda perhatikan, ini cukup rumit dan tidak nyaman, karena kami, pada kenyataannya, menduplikasi logika dan dokumen bisnis.

^{_{Tautan dari slide: FastAPI , SAFRS , rororo}}

Dari yang menarik, saya sarankan Anda untuk melihat FastAPI. Styopa akan memberi tahu Anda lebih banyak tentang ini hari ini . FastAPI membantu Anda menghasilkan spesifikasi di luar kotak. Anda di sana tidak bisa memikirkan apa-apa sama sekali. Cukup tulis kode dan dapatkan spesifikasi yang sudah jadi.

Ada dua kerangka kerja lagi: SAFRS dan rororo. Nama-nama itu tentu saja ajaib. Mereka bekerja sedikit pada model yang berbeda, jangan membuat Anda tidak memikirkan spesifikasinya dan mendapatkannya hanya sebagai efek samping. Sebaliknya, Anda memiliki spesifikasi yang menggerakkan penangan. Secara umum, ini adalah pengembangan yang didorong oleh spesifikasi. Mereka tidak memiliki banyak bintang seperti FastAPI, tetapi bagi saya tampaknya mereka pantas diperhatikan, lihatlah.

Dan akhirnya, kami membahas jenis utilitas apa yang ada di sekitar spesifikasi menggunakan contoh-contoh OpenAPI dan Swagger. Untuk semua poin yang saya buat tautan, lihat pasti, ada banyak hal menarik:

- OpenAPI / Swagger
swagger.io/docs/specification/about

- Contoh tentang falcon + marshmallow + apispec
github.com/marshmallow-code/apispec
github.com/tiangolo/fastapi

- OpenAPI / Swagger
buns
openapi.tools swagger.io/tools swagger.io/tools/open-source/open-source-integrations github.com/APIs-guru/awesome-openapi3

Apa yang saya miliki apakah pesan dari laporan itu? Guys, spesifikasi penulisan bukanlah semacam birokrasi. Dan ini tidak sesulit kelihatannya pada pandangan pertama, tetapi lebih sederhana dan menyediakan banyak alat yang bermanfaat, membuka peluang besar bagi Anda.

Tulis spesifikasinya. Sarankan. Terima kasih banyak.

Semua kode dan tautan tersedia di presentasi .