Example Using Swagger UI for NodeJS

Swagger (http://swagger.io/) adalah salah satu tools yang populer di kalangan API developer terutama digunakan untuk membuat dokumentasi atas API yang telah dibuat.
Contoh official Swagger UI dari website mereka bisa dilihat disini : http://petstore.swagger.io/.

Berikut akan coba saya jabarkan step by step meng-implementasi Swagger UI ini di NodeJS secara sederhana, semua code ada di Github Repository https://github.com/mazipan/sample-swagger-for-nodejs

1. Install Swagger

   npm install -g swagger

2. Create Skeleton

   swagger project create hello-world

3. Start Server

   swagger project start

4. Open Swagger Editor

   swagger project edit

Sampai disini sebenarnya swagger project sudah bisa di RUN, namun ada beberapa hal yang mesti dibenahi untuk membuat API documentation kita sendiri, antara lain :

1. Add more depedency

   Berikut sample beberapa depedency yang saya tambahkan, sebagian adalah untuk mendukung pembuatan API dan halaman Index routing.

       "body-parser": "^1.13.3",
       "cookie-parser": "~1.3.5",
       "express": "^4.12.3",
       "jade": "~1.11.0",
       "lodash": "^4.15.0",
       "mongoose": "^3.6.19",
       "swagger-express-mw": "^0.1.0",
       "swagger-tools": "^0.10.1"
   

2. Change app.js for add Swagger UI

   Import variable SwaggerUI seperti berikut :

   var SwaggerUi = require('swagger-tools/middleware/swagger-ui');

   Tambah code barikut sebelum swaggerExpress.register :

     // Add swagger-ui (This must be before swaggerExpress.register)
     app.use(SwaggerUi(swaggerExpress.runner.swagger));
   

3. Buat API seperti biasa

   Saya tidak akan menjelaskan lagi, bisa dibaca disini

4. Ubah swagger.yaml

   Ubah swagger.yaml di folder api/swagger/swagger.yaml
   Anda bisa manual mengubahnya, atau gunakan Swagger Editor untuk mengubah dan Anda bisa live preview dan auto save atas perubahan tersebut.
   Gunakan perintah ini :

   swagger project edit

   Anda mungkin butuh melihat sample swagger.yaml yang saya buat disini

Semua code bisa di lihat disini : https://github.com/mazipan/sample-swagger-for-nodejs

Demikian sharing dari saya, semoga bermanfaat