Kata Pengantar
Tim di mana saya mengambil langkah pertama saya di bidang penulisan kode industri sedang mengembangkan API yang nyaman untuk fungsionalitas produk perangkat lunak dalam C # (untuk kenyamanan, sebut saja, katakanlah, huruf E), yang telah ada selama bertahun-tahun dan telah memantapkan dirinya di pasar pada sisi yang sangat positif. . Dan di sini, tampaknya, Padawan muda seharusnya tidak memiliki pertanyaan apa pun, tetapi bayangkan bahwa sebelumnya, kemungkinan besar, tentu saja, Anda menulis web-API Anda sendiri, tetapi tidak mungkin untuk audiens yang luas, yang berarti Anda hidup dengan prinsip "Saya menciptakannya sendiri - Saya menggunakannya ", dan jika seseorang tertarik pada fungsionalitas API Anda, maka Anda mungkin akan memberinya file pdf dengan instruksi terperinci (setidaknya saya akan melakukan hal itu). "Di mana saya bisa melihat api fungsional" - Saya bertanya kepada pemimpin tim, berharap untuk mendapatkan tautan ke dokumen teks. "Lihatlah Swagger," jawabnya.
Tunggu, bagaimana produk itu telah berfungsi dengan sukses untuk waktu yang lama, dan API yang Anda tulis hanya untuknya sekarang?
Itu benar, sampai saat ini, E tidak memiliki API publik yang nyaman seperti itu. Faktanya, semua pekerjaan dilakukan melalui antarmuka web, dan back-end terdiri dari banyak layanan internal mikro, yang tidak mungkin untuk diintegrasikan dari luar tanpa pemahaman yang jelas tentang logika bisnis internal, belum lagi fakta bahwa mereka sendiri terdiri dari sebagian besar warisan. Itu perlu untuk memperhatikan klien yang ingin berinteraksi langsung secara langsung dengan server, yang berarti menyediakan mereka dengan API yang indah dan nyaman. Apa yang diperlukan untuk ini? Semua yang ditulis sedikit lebih awal adalah untuk mengambil dan membangun pekerjaan dengan semua layanan internal micros sendiri, serta memberikan dokumentasi yang nyaman dan indah, menjadikannya indah, dapat dimengerti, dan yang paling penting, sukses secara komersial.
Nah, jadi apa itu kesombongan dan apa manfaatnya bagi dunia?
Intinya, Swagger adalah kerangka kerja untuk spesifikasi API RESTful. Pesonanya terletak pada kenyataan bahwa itu memungkinkan tidak hanya untuk melihat spesifikasi secara interaktif, tetapi juga untuk mengirim permintaan - yang disebut UI Swagger, begini tampilannya:
Seperti yang dapat kita lihat - deskripsi lengkap metode, termasuk model, kode respons, parameter kueri - secara umum, jelas.
Dan bagaimana cara kerjanya?
Panduan Hebat untuk Menerapkan Kesombongan di ASP.NET Core
dari awal ada di sini di artikel
ini .
Idenya adalah untuk mengkonfigurasi tampilan menggunakan anotasi khusus untuk metode API, berikut adalah contohnya:
Sombong codegen
Jika Anda benar-benar ingin, Anda dapat langsung menghasilkan klien atau server sesuai dengan spesifikasi Swagger API, untuk ini Anda memerlukan generator kode Swagger-Codegen. Deskripsi dari dokumentasi, saya pikir, tidak perlu dijelaskan:
Ini adalah proyek Swagger Codegen, yang memungkinkan pembuatan pustaka klien API (generasi SDK), stub server dan dokumentasi secara otomatis diberi Spesifikasi OpenAPI. Saat ini, bahasa / kerangka kerja berikut ini didukung:
- Klien API: ActionScript, Ada, Apex, Bash, C # (.net 2.0, 3.5 atau lebih baru), C ++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http -client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Perpustakaan Klien API Google untuk Java, Yakinlah), Kotlin, Lua, Node.js (ES5, ES6, AngularJS dengan anotasi Kompilator Penutupan Google) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (rust, rust-server), Scala (akka, http4s, swagger-async- httpclient), Swift (2.x, 3.x, 4.x), naskah (Angular1.x, Angular2.x, Fetch, jQuery, Node)
- Rintisan server: Ada, C # (ASP.NET Core, NancyFx), C ++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy , Play Framework, PKMST), Kotlin, PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Labu), NodeJS, Ruby (Sinatra, Rails5), Karat (server karat), Scala (Finch, Lagom, Scalatra)
- Pembuat dokumentasi API: HTML, Confluence Wiki
- File konfigurasi: Apache2
- Lainnya: jmeter
Informasi lain, khususnya petunjuk penggunaan, disajikan di sini:
Informasi umumDan di sini:
DetailKesimpulan
Ini adalah tinjauan visual singkat untuk pengembang API pemula, yang tujuannya adalah untuk memberikan gambaran tentang apa itu Swagger, mengapa itu diperlukan dan apa yang memberikan keuntungan utama dari sudut pandang pribadi saya.