Hướng dẫn swagger nodejs example - ví dụ swagger nodejs
Chào các bạn, hôm nay mình sẽ giới thiệu với các bạn một tool khá là nổi tiếng trong việc tạo API docs: Swager UISwager UI Swagger UI là một tool cho phép bất kỳ ai - từ developers cho đến end users - có thể hình dung và tương tác với các tài nguyên API của dự án. Tool này sẽ tự động generates ra API documents từ file config Swagger, với cái nhìn trực quan và việc triển khai trở nên dễ dàng hơn cho phía client. Cài đặt:Bước 1: Tải thư viện Swagger UI. Tải thư viện Swagger UI. Các bạn vào trang chủ https://swagger.io/, tìm tới mục download thư viện Swagger UI sẽ được hướng dẫn clone từ github repository này, paste thư viện này vào project của bạn. Tìm đến thư mục swagger-ui/dist mở file index.html sẽ show lên một trang demo như sauswagger-ui/dist mở file index.html sẽ show lên một trang demo như sau Bước 2: Cấu hình routes trỏ đường dẫn đến file index.html. Cấu hình routes trỏ đường dẫn đến file index.html. Giả sử mình đang xây dựng một ứng dụng Rails app và thả toàn bộ thư viện này vào /public. Trong file routes.rb mình cấu hình như sau:routes.rb mình cấu hình như sau:
Bây giờ khi truy cập tới URL /swaggers bạn sẽ được đưa tới file index.html ở trên/swaggers bạn sẽ được đưa tới file index.html ở trên Bước 3: Tạo 1 file config để cấu hình API docs của project. Tạo 1 file config để cấu hình API docs của project. Sau đây mình sẽ tạo file swagger.yaml với cấu trúc mẫu như sau:swagger.yaml với cấu trúc mẫu như sau:
Một số keys trong file config trên
Bước 4: Trỏ URL đến file config Trỏ URL đến file config Để sử dụng swagger, trong file dist/index.html bạn phải trỏ URL đến file swagger mà bạn vừa config như sau:dist/index.html bạn phải trỏ URL đến file swagger mà bạn vừa config như sau: Tìm đến đoạn js cuối file, trong đoạn khai báo
Hãy sửa URL đó thành URL trỏ tới file swagger.yaml mà bạn vừa tạo ở bước 2, ví dụ file swagger.yaml của mình đang nằm trong thư mục public/api_docs của một Rails app, mình sẽ change như sau:swagger.yaml mà bạn vừa tạo ở bước 2, ví dụ file swagger.yaml của mình đang nằm trong thư mục public/api_docs của một Rails app, mình sẽ change như sau:
Truy cập lại file /swaggers và bạn sẽ có kết quả/swaggers và bạn sẽ có kết quả
Bây giờ, bạn có thể tiếp tục thêm vào paths trong file swagger.yaml để hoàn thành API document cho project của mình.paths trong file swagger.yaml để hoàn thành API document cho project của mình. Tuy nhiên có một vấn đề đó là khi project càng phình to, càng nhiều API thì chẳng phải file swagger.yaml của bạn sẽ dài đến vô tận sao, và lúc đó việc click vào file này để sửa API hoặc thêm mới sẽ trở nên khó khăn rất nhiềuswagger.yaml của bạn sẽ dài đến vô tận sao, và lúc đó việc click vào file này để sửa API hoặc thêm mới sẽ trở nên khó khăn rất nhiều Tổ chức lại file cấu hình với swagger: 2.0
info:
description: Example of Swagger
version: 1.0.0
title: Swagger Demo
schemes:
- http
basePath: "/api/v1"
tags:
- name: Users
description: Everything about user
paths:
/users:
post:
tags:
- Users
summary: Add new user
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: body
name: data
description: New user info
schema:
type: object
properties:
name:
type: string
example: User 1
password:
type: string
example: "12345678"
responses:
200:
description: Create user success
schema:
type: object
properties:
name:
type: string
example: User 1
400:
description: Create user fail
schema:
type: object
properties:
errors:
type: string
example: Some thing went wrong
|