Xem Nhiều 2/2023 #️ Viết Api Document Với Apidocjs # Top 4 Trend | Toiyeucogaihalan.com

Xem Nhiều 2/2023 # Viết Api Document Với Apidocjs # Top 4 Trend

Cập nhật thông tin chi tiết về Viết Api Document Với Apidocjs mới nhất trên website Toiyeucogaihalan.com. Hy vọng nội dung bài viết sẽ đáp ứng được nhu cầu của bạn, chúng tôi sẽ thường xuyên cập nhật mới nội dung để bạn nhận được thông tin nhanh chóng và chính xác nhất.

Về việc viết document nói chung và API document nói riêng

Document là thứ rất quan trọng khi bàn giao một dự án hay cần tham khảo để bảo trì, phát triển dự án đó. Một số bạn dev sẽ nói mình viết code đẹp rồi, cứ vào đọc là hiểu ngay cần gì làm doc và thẳng thừng nói không với doc. Nhưng khi download một source code về, nhận code từ dev khác hay vào maintain một project thì khóc ròng vì không hiểu người ta viết gì cả. Vậy nên:

1. Nếu bạn định code cái gì, hãy dành thời gian ra viết một chút document cho nó 2. Nếu bạn không cập nhật document thì đừng viết nó ra

Với API, dù bạn viết code đẹp thế nào mà không có gì cho client tham khảo ngoài một API mẫu thì khối API bạn viết sẽ sớm trở thành thảm họa với những lỗi kinh điển như: sai kiểu dữ liệu gửi nhận, sai mã lỗi, tốn thời gian support client, mất kiểm soát khi nâng cấp API version… sau đó thì kiểu gì bạn cũng phải ngồi viết document.

npm install apidoc -g

Các thức hoạt động

Folder api-document-output là output của chương trình được generate tự động, bạn không cần đụng tới nó, chỉ cần mở file index.html để xem kết quả.

Bắt đầu viết doc như sau, tạo một file có đuôi cùng với ngôn ngữ bạn dùng để viết API, trong trường hợp này là .js, viết toàn bộ thông tin về một API theo mẫu thế này:

/** * @api {get} /user/:id Request User information * @apiName GetUser * @apiGroup User * * @apiParam {Number} id Users unique ID. * * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. * * @apiSuccessExample Success-Response: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } * * @apiError UserNotFound The id of the User was not found. * * @apiErrorExample Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */ apidoc -i api-document-source/ -o api-document-output/

Với param -i, -o đơn giản là input folder, output folder. Sau đó mở file index.html trong folder out put để xem kết quả. Giao diện đơn giản trình bày tất cả API trong một trang, navigate bằng menu bên trái, toàn bộ chi tiết trình bày ở giữa trang

Happy documentation 🙂

Cách Viết Rails Api Document

Như các bạn đã biết, 1 ứng dụng API sẽ không có giao diện cho người dùng trên trình duyệt, thay vào đó sẽ là các dữ liệu kiểu JSON hoặc XML … được hiển thị mà thôi. Do đó, khi viết 1 ứng dụng API đòi hỏi người viết phải viết Documents (Tài liệu) kèm theo để hỗ trợ cho những Developers sử dụng chúng và đặc biệt là QA, những người sẽ gặp nhiều khó khăn hơn trong việc hiểu được tác dụng của các API.

Có nhiều cách để viết Documents, đơn giản nhất sẽ là viết bằng tay ra file Excel hoặc Word chẳng hạn. Chỉ rõ API này mục đích làm gì, URL để truy cập đến như thế nào, dữ liệu gửi Request là gì, Dữ liệu Response trả về là gì … Xong rồi thì gửi chúng cho bên Developers/QA có như cầu sử dụng để họ đọc. Cách này khá thủ công và tốn nhiều efforts trong khi giá trị mang lại cho những người sử dụng chúng lại chưa chắc đã cao, vì đơn giản chúng không có 1 Format thống nhất và rất dễ thiếu thông tin.

Hôm nay mình sẽ giới thiệu cho các bạn 1 Tool khá nổi tiếng trong việc viết API docs, đó là Swagger (UI). Cụ thể Swagger là gì thì các bạn có thể search để tìm hiểu, Swagger nên ở phạm vi bài viết này mình xin phép không giới thiệu lại, thay vào đó sẽ mình sẽ đi sâu vào cách triển khai Swagger theo cách “Khoa học” và “Developer” nhất có thể.

Quay lại 1 chút thì các bài viết trước đây khi hướng dẫn triển khai Swagger UI thường tiếp cận theo hướng copy UI của Swagger rồi “ném” vào Project của mình (clone lại Repository Swagger hoặc copy file CSS, JavaScript của Swagger) không thì viết sẵn 1 file XML (JSON) rồi render lại chúng ra View.

Còn cách mà “Khoa học” và theo hướng “Developers” ở đây mình muốn nói đến là:

Có khả năng tái sử dụng code, viết Docs cũng như viết Code, cái gì giống nhau là gọi lại dùng được

Dễ dàng mở rộng (Scale), ví dụ: khi thêm 1 trường vào Model hay đổi tên 1 trường chẳng hạn thì file Documents cũng tự động được update chẳng hạn

Tổ chức Trees (Cây thư mục) rõ ràng và khoa học

Trong Rails thì có 2 Gem thường được dùng để Implement Swagger là: swagger-docs và swagger-blocks. Sự khác biệt lớn nhất giữa 2 Gem này là swagger-blocks được support đến v2.0 của Swagger Specification còn swagger-docs chỉ dừng lại ở v1.2, và theo thông tin trên Repo của swagger-docs thì họ chưa có kế hoạch update lên v2.0. Do đó trong Demo này mình sẽ triển khai với gem swagger-blocks.

Note: cả 2 gem kể trên đều không sinh ra giao diện UI/UX theo kiểu Swagger mà chỉ sinh ra 1 file .json phù hợp với format của Swagger UI mà thôi, do đó để có giao diện như Swagger mang lại, chúng ta cần 1 Gem nữa là swaggeruiengine.

Bắt đầu, tạo 1 ứng dụng Rails API bằng cách gõ các lệnh sau trên Terminal:

Sau đó add thêm 2 Gem mình giới thiệu phía trên vào Gemfile rồi bundle chúng:

Note: khi triển khai thực tế mình gặp phải 1 vấn đề khi call API bằng tool Postman – tool hỗ trợ test các Request API – thì Oki nhưng khi Deploy lên Server và call API qua lại giữa các Server thì bị trả về 404, sau 1 hồi search thì tìm hiểu ra là do thiếu config CORS. Để khắc phục thì bạn chỉ cần add thêm vào Gem như sau:

và config cho Rails như sau:

Trên Repo của gem Swagger-Blocks có giới thiệu khá chi tiết về cách Setup Swagger, tuy nhiên mình thấy 1 số điểm chưa thực sự “dry” code cho lắm, do đó mình sẽ custom lại Trees (cấu trúc) của Swagger trong Project của mình 1 chút để tận dụng được những cái sài chung (tái sử dụng code í mà) như kiểu các Paramerter hay được gọi đi gọi là hoặc là các Response phổ biến (lỗi 404 hay 500 chẳng hạn). Đồng thời cũng giúp chúng ta dễ dàng mở rộng code khi cần thiết trong tương lai.

Cấu trúc thư mục của Swagger khi đó sẽ như thế này:

So sánh với tài liệu trên Repo của Swagger-Blocks thì cách tổ chức của mình có 1 vài điểm mà cá nhân mình nghĩ sẽ rành mạch và rõ ràng hơn.

Theo Swagger hướng dẫn thì mỗi Documents sẽ ứng với 1 Controller, cách viết này khá dễ hiểu, nhưng các bạn có thế dễ dàng nhận ra là Controller sẽ bị phình to “cực kỳ” nhanh nếu đặt Docs trong đó. Và Controller cũng không phải là là 1 nơi lý tưởng để xử lý Docs. Do đó, chúng ta hãy tách ra thành 1 Module riêng biệt – chuyển xử lý Docs. Cụ thể ở đây mình sẽ để vào trong thư mục concern/swagger rồi sau đó Include lại vào Controller.

Sẽ có rất nhiều Parameter dùng chung, ví dụ: userID được dùng chung khi get thông tin của User cũng như update thông tin user chẳng hạn. Do đó mình tạo ra 1 file chúng tôi để chứa những thứ dùng chung, khi cần dùng thì sẽ include lại vào file Docs (ở đây là user_api.rb)

Tương tự, sẽ có rất nhiều Response Error được dùng chung, kiểu lỗi 401 – not authorize hay là 404 – not found Records do đó mình tạo ra 1 file error_response.rb để viết chung, khi cần lại include vào file chứa Docs (ở đây là user_api.rb)

Response Success 200 tuy mỗi API sẽ trả về 1 thông tin khác nhau, nhưng không phải là không có điểm chung. Chẳng hạn, các API sau đều trả về thông tin của User sau khi Request thành công đó là: API show, API edit thông tin của User và API login. Do đó, chúng ta phải tìm cách tái sử dụng Code. May thay, với Swagger chúng ta có thể sử dụng $ref để gọi tới 1 schema được định nghĩa trước đó (ở đây là: user_schema.rb trong modes/concern/swagger)

Chú ý cần tạo Router cho Documents để còn biết URL mà xem trên trình duyệt.

Sau khi tạo Router, thì chúng ta cũng tạo ra 1 controller ứng với router này và định nghĩa các thông số cơ bản của API Documents như:

Version Swagger sử dụng -Tittle, Description của API

Đường dẫn mặc định của API

Kiểu dữ liệu sinh ra của API (thường là Json hoặc có thể là XML) ….

Trong method index của api_docs_controller các bạn nhớ gọi method để render ra những thông tin API mà mình muốn viết Docs.

Đến đây là các bạn có thể bật server lên và vào URL: localhost:3000/api_docs.json để xem thanh quả rồi.

Chúng ta sẽ dùng gem swagger_ui_engine và config 1 chút để có giao diện Swagger UI cho dữ liệu json mình vừa tạo ra ở bên trên như sau:

Xong. Tới đây bạn có thể restart lại server, truy cập lại URL localhost:3000/api_docs để thấy thành quả.

Cấu Hình Swagger Ui Để Viết Document Cho Api

Chào mọi người, bài viết này mình sẽ hướng dẫn các bạn làm thế nào để chạy và test một document API được viết bằng Swagger. Ở đây mình không đề cập đến các khái niệm, cú pháp và cách viết một file document API sử dụng Swagger, những thứ đó các ban có thể tham khảo ở trang chủ của Swagger chúng tôi mà chỉ đề cập cách để config swaagger làm thế nào để chạy trong dự án mà bạn đang làm mà thôi.

Hạn chế của các gem swagger trong Rails

class Api::V1::UsersController < ApplicationController swagger_controller :users, "User Management" swagger_api :index do summary "Fetches all User items" notes "This lists all the active users" param :query, :page, :integer, :optional, "Page number" param :path, :nested_id, :integer, :optional, "Team Id" response :unauthorized response :not_acceptable, "The request you made is not acceptable" response :requested_range_not_satisfiable end .........

Mặc dù nó không ảnh hưởng gì đến quá trình hoạt động của API, tuy nhiên nó gây khó chịu cho việc đọc code và việc nhúng vào file controller như thế này quả là không hay tí nào, vả lại nó cũng không hoàn toàn tuân theo cách viết document trên trang chủ của Swagger, nên đôi khí sẽ khó để config cho lập trình viên. Và thế là mình suy nghĩ làm cách nào để nhùng trực tiếp thư viện của thằng Swagger vào project của mình hay không ? Sau một hồi tìm hiểu thì Ơ rê ka ra rồi, và đôi khi nó đơn giản đến không ngời.

Option 1: Import thư viện Swagger UI

Thực chất thì để hiển thị một document API cho người dùng đọc, thì chỉ cần 2 thứ, đó là thư viện Swagger UI và file document API được viết theo cú pháp và cấu trúc của Swagger có định dạng là *.yaml. Để cài đặt nó trong project của mình thì bạn làm như sau:

Thực hiện pull thư viện swagger-ui từ trang github của nó vào project của mình như sau:

git clone git@github.com:swagger-api/swagger-ui.git public/swagger-ui

Sau đó config trong file config/routes.rb để Rails có thể nhận đường dẫn đến file html tĩnh để chạy màn hình document API:

get '/swagger-ui', to: redirect('swagger-ui/dist/index.html?url=%2Fswagger.yaml')

Và file document API mẫu của minhf là chúng tôi có nội dung như sau:

swagger: 2.0 info: description: Example of integration swagger with Rails version: 1.0.0 title: Rails 5 Swagger schemes: - http host: "localhost:3000" basePath: "/api/v1" paths: /users: post: tags: - Register user description: Create new user produces: - application/json parameters: - in: "formData" name: "user[nickname]" required: true - in: "formData" name: "user[birthday]" required: true type: string - in: "formData" name: "user[avatar_id]" required: true type: number responses: 200: description: User created

Các bạn chú ý, như mình đã nói ở trên thì để chạy màn hình hiển thị document API của thằng swagger, thì ở đây mình đã pull thư viện swagger UI về project của mình và mình có file swagger.yaml, việc của mình chỉ là khai báo đường dẫn vào đến file chạy mà thôi. Sau khi đã cài đặt xong, khởi động server Rails và truy cập vào đường dẫn: localhost:3000/swagger-ui, mình sẽ có kết quả như sau:

Hura, vậy là mình đã nhúng thành công nó, thấy có vể đơn giản quá nhỉ, và nó thực sự ok nếu các bạn không có yêu cầu gì thêm. Tuy nhiên vẫn có một vấn đề đặt ra ở giải pháp này đó là thư viện Swagger UI có dung lượng lên đến gần 200MB, và nó được push trực tiếp vào sourecode của dự án mình, thực sự thì k hay tí nào, và việc get đến url document API trực tiếp trên server API đang chạy cũng làm cho dễ bị lộ cấu trúc của API, vì thực chất thằng giao diện của Swagger UI là một file tĩnh và nó chỉ handle lại response trả về mà thôi. Hãy tương tượng nó như thằng Postman, tuy nhiên nó cung cấp thêm phần mô tả cho API mà thôi.

Option 2: Swagger with Docker

Như đã nói ở trên, để chạy swagger thì chỉ cần thư viện swagger-ui và file document API. Và ở đây mình muốn chạy server document API riêng với server API của mình. May thay Swagger đã support tận răng cho người dùng một image để chạy trên docker mà không cần phải config gì. Các bước thực hiện nó như sau:

Step 1: Cài đặt Docker.

Step 2: Sau khi cài đặt docker thì các bạn tiến hành pull image của swagger ui về bằng cách sử dụng command sau:

docker pull swaggerapi/swagger-ui

Step 3: Convert file *.yaml thành *.json

Step 4: Sau đó chạy command sau để khởi chạy server swagger

docker run -p 80:8080 -e "SWAGGER_JSON=/api.json" -v chúng tôi swaggerapi/swagger-ui

Step 5: Config CORS cho rails server API. Phương pháp này có một hạn chế đó là giữa 2 server phải giao tiếp với nhau. Vì vậy chúng ta phải config rack cors cho rails API. Ở đây mình sử dụng gem rack-cors, 1 gem thông dụng cho việc setting này. Các bạn có thể tham khảo cách config ở trang github của nó: rack-cors gem.

Step 6: Khởi động server API và kiếm tra thành quả của mình thôi.

Option 3: Take it easy

Ở hai option trên, thì mình đã cung cấp cho các bạn cách làm thế nào để hiển thị một document viết bằng swagger, tuy nhiên, giả sử mình chỉ có một dự án nhỏ, API không nhiều lắm, có cần phải tốn công tải nguyên cả thư viện về hoặc phải cài docker để build hay không, giống như dùng dao mổ trâu mà giết gà vậy ? Sau khi vọc thư viện của nó thì mình nhận ra thằng swagger UI thì khi chạy, nó sẽ tìm đến file chúng tôi trong thư mục dist của thư viện.

Nếu để ý thì các bạn có thể nhận ra rằng để hiển thị một document đơn giản thật ra k cần nhiều lắm, 1 file css có tên là chúng tôi 2 file js là chúng tôi chúng tôi Uhm, vậy mấy thư viện css và js đó lấy đâu ra, tất nhiên là nó nằm ở cùng thư mục với file chúng tôi rồi, tuy nhiên, có cách nào đơn giản hơn nữa không ??? Search google 1 xí là ra ngay ấy mà, phải nói là thằng swagger này đã support tận răng cho dev, mình lên cdn search cái là ra liền à.

Và ở đây bạn chỉ cần thay attribute src của thẻ script và thẻ style thằng những link thư viện online tương ứng mà thôi. Vậy còn file document thì sao, đọc kĩ 1 tí thì bạn sẽ thấy dòng này.

url: "http://petstore.swagger.io/v2/swagger.json",

Thực ra đường dẫn này swagger cung cấp cho mình đến file document mẫu mà swagger cung cấp. Vì thế, để chạy document của riêng mình, thì chỉ cần parse file document API của chúng ta, up lên một server online nào đó và thay thế đường dẫn trên bằng đường dẫn đến file json của mình thôi. Ví dụ như file mình đã chỉnh sửa như sau:

Như vậy, với cách này, chúng ta chỉ cần duy nhất 1 file tĩnh chúng tôi theo mẫu của thằng swagger là đã hiển thị được document API rồi. Cực kì đơn giản phải không.

Kết luận

Như vậy ở bài này mình đã hướng dẫn cho các bạn các cách làm thế nào để config swagger để hiển thị document API. Tùy từng trường hợp và yêu cầu của mỗi người để chọn ra option phù hợp nhất, vì không có cái nào là tốt nhất cả. Ngoài thằng Swagger ra thì còn có thằng API Blueprint cũng được nhiều lập trình viên sử dụng. Hy vọng mình sẽ có điều kiện tìm hiểu và giới thiệu nó cho các bạn trong tương lai. Cảm ơn các bạn đã theo dõi.

Cách Tạo Api Với Rails (Phần 2) Viết Test Case

Tiếp theo Cách tạo API với Rails (phần 1) Mình sẽ hướng dẫn cách test căn bản cho API mình tạo. Thật ra mà nói thì mình phải viết test trước khi làm nhưng mà để tránh việc gây khó hiểu nên mình xin mạn phép đảo ngược qui trình.

Để thuận lợi hơn cho việc viết test case mình sử dụng gem rspec-rails

Test case thuộc tính của model mình đã tạo

Để dễ dàng hơn trong việc viết test case mình sử dụng thêm 2 gem:

Gem factory_girl_rails để tạo fixture data

Gem shoulda

Nhớ bundle install lại sau khi add gem

Chúng ta tạo lại model traveler

rails g model traveler first_name:string last_name:string birthday:datetime gender:string

Bây giờ cấu trúc app của chúng ta sẽ xuất hiện thêm phần này ( màu xanh lá cây)

Tạo fixture data

Vào file sau spec/factories/travelers.rb để kiểm tra lại fixture data mà FactoryGirls đã tạo. Mình sẽ edit lại một tí ( dựa vào gem ffake )

FactoryGirl.define do factory :traveler do first_name { FFaker::Name.first_name } last_name { FFaker::Name.last_name } birthday { FFaker::IdentificationESCO.expedition_date } gender { FFaker::Gender.maybe } end end

Test các thuộc tính của model

Bạn tạo model cho traveler và test cho traveler nên bạn sẽ viết test case tại file traveler_spec.rb

Vào file sau spec/models/traver_spec.rb để viết test case

require 'rails_helper' describe Traveler do before { @traveler = FactoryGirl.build(:traveler) } subject { @traveler } it { should respond_to(:first_name) } it { should respond_to(:last_name) } it { should respond_to(:gender) } it { should respond_to(:birthday) } end

Kiểm tra kết quả của test case Tại terminal bạn gõ theo cấu trúc rspec **đường đẫn file muốn test**

rspec spec/models/traveler_spec.rb

Test respond trả về khi request api

Test response code trả về thành công là 200

Test data trả về gồm những thành phần gì

require 'spec_helper' describe V1::TravelersController do before do @traveler = FactoryGirl.create :traveler get "/v1/travelers", format: :json end it 'return traveler information' do traveler = JSON.parse(response.body, symbolize_names: true).first expect(traveler[:first_name]).to eql @traveler.first_name expect(traveler[:last_name]).to eql @traveler.last_name expect(traveler[:gender]).to eql @traveler.gender expect(traveler[:birthday].to_s.to_i).to eql @traveler.birthday.to_s.to_i end it 'response code' do expect(response).to have_http_status(200) end end

Run lệnh này để kiểm tra kết quả

rspec spec/requests/v1/travelers_controller_spec.rb

Yah! đã xong

Bạn đang xem bài viết Viết Api Document Với Apidocjs trên website Toiyeucogaihalan.com. Hy vọng những thông tin mà chúng tôi đã chia sẻ là hữu ích với bạn. Nếu nội dung hay, ý nghĩa bạn hãy chia sẻ với bạn bè của mình và luôn theo dõi, ủng hộ chúng tôi để cập nhật những thông tin mới nhất. Chúc bạn một ngày tốt lành!