Irfan Maulana's Journal

Example Using Swagger UI for NodeJS

Irfan Maulana

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