Cách Viết Tài Liệu Api Document Cực Đơn Giản!!!, Giới Thiệu Swagger

1. Lời mở đầu

Kỳ này trên trường mình bao gồm dạy môn về lập trình áp dụng Android. Bài tập lớn cho cả kỳ của chính mình là làm ra 1 áp dụng với yêu thương cầu: có tác dụng cái gì cũng được, áp dụng càng những công nghệ, càng các kỹ thuật thì điểm càng cao.

Bạn đang xem: Cách viết tài liệu api

Với yêu mong đó bản thân đã quyết định làm 1 API hệ thống cho ứng dụng Android. Thừa trình khám phá kiến thức mới có nhiều khó khăn, giải quyết chấm dứt vấn đề A thì lại xuất hiện vấn đề B. Nhưng quá trình này cũng rất thú vị.

Code xong xuôi server rồi thì mình nghĩ tới 1 vấn đề: những đầu API như này thì có tác dụng sao report hết được kết quả? Ghi vào report word thì trông "cùi bắp" quá. Bắt buộc làm cái gì đó thú vị hơn.

Và thay là mình đọc thêm và biết về Swagger UI.

2. Swagger UI

Swagger UI là một trong những công cụ để ngẫu nhiên ai, chỉ cần truy cập trang API document là có thể hình dung và địa chỉ với những tài nguyên API của dự án. Swagger UI này vẫn tự tạo nên các API document từ file config Swagger.

Giao diện của Swagger UI có điểm mạnh là đẹp, color sặc sỡ bắt mắt, thậm chí hoàn toàn có thể thực hiện luôn request tới từng đầu API và nhận về kết quả.

Để cài đặt Swagger UI thì họ cần clone repo swagger-api trên Github về tại đây: https://github.com/swagger-api/swagger-ui

Sau đó tiến hành cài đặt thủ công hoặc docker theo như chỉ dẫn tại: https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/

Nhưng mình đang không thiết đặt nhiều cách dài dòng như vậy. Trong nội dung bài viết này, mình vẫn hướng dẫn các bạn tạo 1 trang API document cùng với Swagger:

ĐƠN GIẢN lúc CÀI ĐẶTĐƠN GIẢN lúc TÙY CHỈNH DỮ LIỆUĐƠN GIẢN lúc DEPLOY LÊN SERVER3. Có tác dụng API document cực kỳ ĐƠN GIẢN

3.1. Cài đặt

Bước 1: chúng ta sẽ download repo bên trên github về trên https://github.com/swagger-api/swagger-ui

Bấm vào nút download ZIP để sở hữu về. Sau khoản thời gian giải nén ra bọn họ sẽ có tổng thể các file đề nghị thiết.

Bước 2: bởi vì làm dễ dàng và đơn giản và cấp tốc nên họ chỉ cần các file trong folder dist thôi. Bọn họ copy hết toàn bộ các tệp tin trong thư mục này ra 1 một nơi khác. Tiếp nối xóa mấy cái file và thư mục swagger đi luôn, mấy cái đó hết chức năng rồi.

3.2. Cấu hình thiết lập giao diện

Để sửa hình ảnh thì họ sẽ sửa tệp tin index.html. Khi chỉnh sửa file index thì chúng ta cũng có thể thay đổi mọi phần tôi đã khoanh đỏ dưới đây

Để thay đổi phần tiêu đề với icon bên trên tab trình duyệt, bọn họ sẽ sửa nội dung trong thẻ và đường truyền của 2 cái ảnh.

Để biến đổi danh sách các API, chúng ta sẽ sửa mẫu url dưới đây

Thay bởi lấy dữ liệu từ 1 url ngoài, họ sẽ sở hữu trực tiếp tài liệu từ file json luôn luôn (chúng ta sẽ tạo và thiết yếu sửa tệp tin json chứa tài liệu sau). Để biến đổi chỉ cần:

Thêm 1 thẻ script xác định file json đựng dữ liệu: Đổi mẫu url thành spec

Để xóa thanh Explore đi, chúng ta sẽ xóa những đoạn sau

script src="https://viblo.asia/swagger-ui-standalone-preset.js" charset="UTF-8"> script>và

plugins: < Swagger
UIBundle.plugins.Download
Url>,layout: "Standalone
Layout"và mẫu Swagger
UIStandalone
Preset vào phần preset

Sau những chỉnh sửa trên, file index.html trở nên như sau:

UIBundle( spec: spec, dom_id: "#swagger-ui", deep
Linking: true, presets: < Swagger

3.3. Cấu hình thiết lập dữ liệu

Ở trên bản thân đã nói đến việc thêm 1 file spec.js để xác minh các đầu API và tin tức hiển thị. Hiện giờ chúng ta sẽ sửa đổi dữ liệu trong file js này.

Cấu trúc cơ phiên bản của tệp tin spec.js như sau:

var spec = swagger: "2.0", // Phiên bạn dạng Swagger UI info: description: "Các tin tức mô tả về dự án công trình và API", version: "1.0", // Phiên bản API title: "Tên dự án" , host: "localhost:3000", // Server với port deploy API base
Id: "create
New
Admin
Account", consumes: <"multipart/form-data">, // Loại dữ liệu gửi đi produces: <"application/json">, // Loại tài liệu trả về parameters: < // những tham số "in": "form
Data", // thông số được gửi lên từ size "name": "username", // tên tham số "required": "true", // tham số là cần "schema": "type": "string" // Loại dữ liệu của tham số là chuỗi , "description": "username cho thông tin tài khoản admin mới" , "in": "form
Id: "get
Admin
Account
By
Id: "change
Password
Admin
Account
By
ID", consumes: <"multipart/form-data">, produces: <"application/json">, parameters: < "in": "path", "name": "id", "required": "true", "schema": "type": "integer", // giao diện tham số là số nguyên "minimum": "1" // giá trị thấp nhất là một trong những , "description": "id của thông tin tài khoản admin" , "in": "form
Data", "name": "password", "required": "true", "schema": "type": "string" , "description": "password bắt đầu của tài khoản admin" >, responses: 200: description: "đổi mật khẩu đăng nhập thành công" , , security: < > , security
Definitions: // thông tin về api key sử dụng để triển khai request api_key: type: "api
Key", // Thuộc các loại api key chuẩn xác name: "api_key", // thương hiệu trường đựng api key đảm bảo in: "header", // API key được để trong phần header của request , definitions: // tin tức các đối tượng người dùng sẽ trả về admin: // Tên đối tượng người sử dụng type: "object", // Loại đối tượng người dùng là object properties: // các thuộc tính của đối tượng người sử dụng id: // Tên trực thuộc tính type: "integer" // Loại tài liệu là số nguyên , username: type: "string" // Loại dữ liệu là chuỗi , password: type: "string" };Mình đã phản hồi hết tin tức của từng trường tài liệu rồi. Phụ thuộc vào nhu cầu, họ chỉ cần chuyển đổi thông tin là có thể đạt được công dụng mong muốn.

Xem thêm: Tài liệu ôn thi tokutei thực phẩm, tài liệu thi tokutei ngành chế biến thực phẩm

Tính năng gởi request tới API server của Swagger UI vẫn gửi request phụ thuộc vào các thông tin chúng ta khai báo. Tùy vào code back-end mà bọn họ cần đổi khác tương ứng, còn nếu như không khi giữ hộ request có khả năng sẽ bị lỗi.

3.4. Deploy

Chúng ta chỉ việc copy cả folder lên web hệ thống là hoàn toàn có thể truy cập được. Sau khi tối giản, xóa cục bộ các file không quan trọng đi thì thư mục nên deploy chỉ với lại như sau:

Như vậy là bọn họ đã có một trang API Document rất nhẹ, mua cực nhanh trong những lúc làm cực đơn giản.

Mở bài

Mình là 1 trong những người học môn Văn thời điểm xưa chỉ được 4/10 điểm, được thầy giáo văn thấy rất đẹp trai, nhân từ mà nâng điểm lên 5 cho được học sinh Khá :v, phải ngồi nghĩ hoài chiếc mở bài sao cho phù hợp mà không ra.

Tóm gọn gàng là bài bác này bạn muốn chia sẻ trải nghiệm cá thể khi áp dụng kỹ năng và kiến thức đọc/viết API cơ phiên bản vào trong các bước Business Analyst như thế nào. Đặc biệt là các bạn từ mảng non-IT chuyển hẳn qua làm BA, thì đôi khi để học hiểu sâu vào API thì đang tốn không hề ít thời gian, và đôi khi thấy khó khăn mà trường đoản cú bỏ. Phải mình sẽ share dưới dạng mọi trải nghiệm mình đã chạm mặt để các chúng ta có thể hình dung một giải pháp dễ rộng nhé.

API là gì?

Trước không còn cũng buộc phải hiểu 1 chút về API là gì nha.

API là viết tắt của Application Programming Interface – dịch nôm mãng cầu là đồ họa lập trình ứng dụng. Nó là một trong những giao diện (interface) thân hệ thống/ứng dụng này cùng với hệ thống/ứng dụng khác – tài liệu được trao đổi qua lại trong những hệ thống/ứng dụng này.

Profile bản thân về API

Thực tế là ngơi nghỉ đại học, bản thân học chuyên ngành chuyên môn phần mềm, nên từ thời điểm năm 2 cũng đã ban đầu nhảy vào code lung ta lung tung, rồi tập kết nối API giữa ứng dụng và firebase các kiểu, rồi chuyển sang học Swift, đem data tự API nhằm đẩy vào vào tableview, buộc phải cũng gọi sơ sơ về cách API hoạt động. Cũng có thể có một thời hạn mình tham gia kiểm tra web có kết nối API và buộc phải dùng postman để check dữ liệu vận động có đúng hông. Dẫu vậy mãi về sau khi đi làm BA, mình không thể code nữa, nhưng kỹ năng và kiến thức còn ở đó cũng dùng được tại 1 mức đọc/hiểu nhằm từ đó tham gia được các dự án có tương quan API. Còn liên kết Postman thì mình quên rồi – giả dụ mò lại thì đc, code cũng chẳng viết được mấy dòng :(( – khóc á.

Tình huống áp dụng kỹ năng về API

Tính tới lúc này thì từ thời gian mình chuyển hẳn qua làm vị trí bố đến giờ, hầu hết tất cả dự án mình tham gia đều sở hữu dính tới API, và tiếp sau đây là thay mặt các cases mình bao gồm đụng chạm nó trong các dự án quá khứ nhé.

Case 1: liên kết thanh toán/donation trải qua các cổng thanh toán như Paypal, Stripe, …Case 2: tách bóc hệ thống web bây giờ từ kết nối GUI thẳng với CMS trong 1 thể thống nhất thành một cổng web API và những interface không giống nhau để đưa dữ liệu hiển thị.Case 3: Luồng các tính năng trong thanh toán/chuyển khoản – vận động có đi qua một hay những cổng trung gian nối API thân các hệ thống với nhau – này mình thấy giờ phần nhiều các ứng dụng lớn khủng đều áp dụng.Case 4: liên kết bên đồ vật 3 vào để run business riêng mang đến – ví dụ kết nối 1 luồng để vé xe mang đến chuỗi booking (hotel, xe, tour du lịch)Các tình huống khác nhưng mình chưa đặt ra tên, nên đại diện 4 trường hợp trên thôi nhé.

Đa số những dự án mình có tác dụng thuộc dạng API liên kết về để xử lý nội bộ, và chưa thử phân tích phần API trỏ ra cho các khách hàng/dự án mặt ngoài, đề xuất sẽ không đàm đạo phần analysis để tối ưu roi đồ các kiểu nhé – vày mình cũng chưa có kinh nghiệm, không dám bàn phần này. Và các loại API khác mình không kể thì coi như mình quăng quật qua, chỉ tập trung vào phần API mình đề cập trong bài viết nha, vì chưng mình sự hiểu biết trên gg thì còn nhiều các loại API mà lại mình chưa chạm tới bao giờ.

Lợi thế khi biết đọc/hiểu về API

Mình lạc quan là nhờ vào biết đọc/hiểu sơ về API, tạo cho mình xây dựng cũng như hiểu dự án công trình nhanh hơn khôn xiết nhiều. Dưới đây là những điểm mạnh của 1 BA lúc biết đọc/hiểu về API

Viết tài liệu chuẩn, đúng mực hơn khi biết được tài liệu gọi đi đâu, gọi như vậy nào, tài liệu truyền đi và truyền về tất cả những tin tức ra sao.Đỡ bắt buộc hỏi developer vượt nhiều câu hỏi về tài liệu API quý khách gửi đến bạn, nhiều khi dev không có rãnh để ngồi với bạn sẽ giúp bạn gọi hoặc vấn đáp cho bạn, vị họ cũng có phần việc của họ và chúng ta cũng bận lắm.Kiểm tra được API của KH hỗ trợ có tương xứng với chức năng đang xây dựng hay không? Thiếu tốt đủ, tự đó có thể đưa ra giải pháp giải quyết tương xứng từ cách phân tích. Này là hồi trước mình gồm làm dự án, vì nhân kiệt lên vô cùng gấp, nên hai bên sẽ chạy tuy nhiên song phần việc, đầu mình thì lên tài liệu, đầu KH thì lên API để kết nối – và các thứ chỉ dựa trên trao đổi tổng quan tiền qua cuộc họp mà chưa tồn tại 1 tài liệu nào chi tiết cả, nên lúc đó nếu tía biết API, thì rất có thể trực tiếp thương lượng sớm phần tài liệu ra vô giữa khối hệ thống 2 mặt và cập nhật tài liệu/API mang đến phù hợp, đảm bảo an toàn tiến độ.Đưa dữ liệu tương xứng để hiển thị lên màn hình giao diện (client), tương tự như lỗi tương ứng. Này thuận tiện nhận thấy trong dự án công trình case 4 của mình, bản thân biết được tài liệu nào API có thể cung cung cấp ra được, từ đó vẽ màn hình hiển thị có mọi thông tin phải chăng được chuyển lên, kiêng vẽ lên màn hình, lên kiến thiết UI/UX các kiểu thì mới có thể hớ ra là API ko trả tài liệu được… mà lại nếu API từ mặt thứ 3 – chỉ gồm 2 cách, một là bên mình bỏ và sửa lại UI, 2 là bảo mặt thứ 3 bổ sung trường vào API … với việc cập nhật lại tác động tới những đối tác khác của bên thứ 3 đó
. Lợi thế đó