Pernahkah Anda ingin memiliki dokumentasi angkuh untuk API ekspres Anda berdasarkan anotasi? Saya punya. Dan sayangnya tidak menemukan cara untuk melakukannya tanpa harus secara manual membuat file swagger.json . Harapan saya sederhana seperti ini: Saya ingin memiliki aplikasi ekspres bersih dengan banyak titik akhir dan saya ingin menyimpan dokumentasi kesombongan untuk setiap titik akhir dekat dengan implementasi titik akhir, bukan dalam file terpisah.

Mungkin saya hanya kurang memiliki beberapa keterampilan google, tetapi saya memutuskan bahwa akan lebih mudah bagi saya untuk membuat alat seperti itu. Dan ini dia: mgr-swagger-express

Memulai

Contoh di sini akan ditulis dalam TypeScript, tetapi hal yang sama dapat dilakukan dalam proyek Javascript.
Jadi bayangkan aplikasi ekspres klasik:

Di sini kita memiliki "Buku" sumber daya dan beberapa titik akhir CRUD dasar. Pertanyaannya adalah "Bagaimana Anda menambahkan dokumentasi Swagger keren ke API ini?" Saya benar-benar ingin melakukannya menggunakan anotasi untuk menjaga setiap dokumentasi titik akhir dekat dengan titik akhir itu sendiri.

Inilah yang dapat Anda lakukan dengan mgr-swagger-express :
index.ts :

BookService.ts :

Ada kode bot yang lebih banyak, tetapi sekarang kita memiliki semua dokumentasi kesombongan berbaring di dekat titik akhir itu sendiri.
Mari kita lihat apa yang terjadi di sini:

• Dalam file indeks, kami membuat aplikasi ekspres, seperti biasa. Juga kita harus menginisialisasi semua middlewares (bodyParser menjadi yang paling penting).
• Setelah ini, kami memanggil SET_EXPRESS_APP untuk mengatur objek aplikasi secara global. Dengan cara ini mgr-swagger-express akan dapat melampirkan handler ke titik akhir
• Hanya setelah ini kami dapat mengimpor layanan dengan anotasi. Tidak harus berupa kelas, bisa juga hanya fungsi.
• Kemudian kami membuat instance dari layanan kami (atau memanggil fungsi init jika tidak menggunakan kelas)
• Dan kami menghasilkan konfigurasi swagger berdasarkan semua anotasi yang kami miliki dalam proyek dan melampirkannya ke aplikasi kami menggunakan paket swagger-ui-express

Di dalam layanan, ada beberapa hal yang terjadi, tetapi mari kita berhenti pada beberapa saja. Segala sesuatu yang Anda dapat dengan mudah menemukan di repo mgr-swagger-express:

• Dalam konstruktor kita memanggil fungsi addSwaggerDefinition . Ini mendaftar model kesombongan dengan nama yang diberikan. dalam kasus kami, kami mendefinisikan BookDefinition bawah nama Buku untuk referensi setelah itu oleh #/definitions/Book
• Semua penangan diberi penjelasan dengan @GET @POST @PUT @DELETE . Mereka semua mengambil argumen objek bertipe SwaggerEndpoint :
  

   path: string; auth?: string; description?: string; tags?: string[]; parameters?: SwaggerURLParameter[]; query?: SwaggerQueryParameter; body?: SwaggerBodyParameter; success?: SwaggerSuccessResponse; 

  
  

  Ini pada dasarnya objek definisi titik akhir angkuh klasik, tidak ada yang istimewa, kecuali untuk bidang auth, tapi aku akan kembali ke sana di masa depan

  
  Semua penangan harus memiliki tanda tangan berikut:
  

   (args: object, context: Context) => Promise<any> 

  
  

  Objek args berisi semua parameter yang dilewati ke titik akhir Anda. Ini bisa berupa parameter URL (seperti book_id dalam contoh kami), parameter kueri, atau bahkan nilai badan.

  
  
  

  Objek konteks digunakan untuk menangani otentikasi dan keamanan, tetapi sekali lagi, tentang hal itu nanti.

  
  

  Kesimpulan

  
  

  Sekarang kita memiliki API express CRUD sederhana yang dianotasi dengan Swagger dan UI swagger yang indah, di mana semua definisi Swagger diletakkan di dekat implementasi titik akhir. Seperti biasa - selalu senang mendapat tanggapan! ️