Tìm hiểu về API Document - Trang Chủ

Nhân tiện dự án Bất Động Sản mình đang tăng trưởng API, ngoài coding ra cũng đang tư vấn Khách hàng phần tạo tài liệu, ngày hôm nay mình mạo muội khám phá một chút ít khái niệm về API, API document, Swagger, Basic Structure … tổng hợp trong bài viết này. Hy vọng những thông tin cơ bản dưới đây sẽ hữu dụng cho những bạn newbie như mìnhBài viết sử dụng những nguồn tìm hiểu thêm sau đây :https://quantrimang.com/giao-dien-lap-trinh-ung-dung-api-la-gi-148288

https://swagger.io/blog/api-documentation/what-is-api-documentation-and-why-it-matters/

Bạn đang đọc: Tìm hiểu về API Document – Trang Chủ

https://swagger.io/docs/specification/2-0/basic-structure/https://swagger.io/resources/articles/difference-between-api-documentation-specification/https://www.altexsoft.com/blog/engineering/what-is-api-definition-types-specifications-documentation/Trước hết, tất cả chúng ta sẽ cùng tìm hiểu và khám phá xem API là gì nhé .

Tóm Tắt

API là gì?

API là viết tắt của Application Programming Interface ( Giao diện lập trình ứng dụng ), một ứng dụng trung gian được cho phép liên kết với những thư viện và ứng dụng khác .Khi sử dụng một ứng dụng trên điện thoại di động, ứng dụng liên kết Internet và gửi tài liệu tới sever. Sau đó, sever lấy ra tài liệu đó, diễn giải nó, thực thi những hành vi thiết yếu và gửi nó trở lại điện thoại thông minh. Ứng dụng sau đó sẽ diễn giải tài liệu đó và trình diễn thông tin bạn muốn theo cách hoàn toàn có thể đọc được .

Để dễ hiểu, hãy lấy một ví dụ quen thuộc sau .Hãy tượng tưởng, trong một nhà hàng quán ăn, bạn là người mua và căn phòng nhà bếp là “ mạng lưới hệ thống ” chuẩn bị sẵn sàng thực đơn cho bạn. Cái còn thiếu ở đây là link quan trọng để truyền đạt nhu yếu của người mua tới căn phòng nhà bếp và chuyển đồ ăn tới bàn cho họ. Liên kết quan trọng này chính là bồi bàn hoặc API. Người bồi bàn – API là người đưa tin, sẽ nhận nhu yếu gọi món và truyền đạt lại tới phòng bếp – mạng lưới hệ thống. Sau khi thức ăn đã chuẩn bị sẵn sàng, bồi bàn sẽ chuyển nó tới người mua .

API và các loại tài liệu

API Documentation

API Document là tài liệu hướng dẫn tìm hiểu thêm cho API – Giúp người dùng API biết cách sử dụng API hiệu suất cao. Tài liệu API thường dành cho những lập trình viên, giúp lập trình viên hoàn toàn có thể đọc và hiểu ; do đó việc tạo ra một tài liệu API được phong cách thiết kế tốt, tổng lực và dễ theo dõi là cực kỳ quan trọng .API Document gồm có những hướng dẫn về cách sử dụng hiệu suất cao và tích hợp với một API. Nó là một tài liệu ngắn gọn, chứa toàn bộ những thông tin được nhu yếu để thao tác với API, với thông tin cụ thể về những function ( hàm ), class ( lớp ), return type ( kiểu tài liệu trả về ), những argument ( tham số ), … được tương hỗ bởi những bài hướng dẫn và ví dụ .Tài liệu hướng dẫn API Document thường được triển khai bằng cách sử dụng những công cụ tạo, bảo dưỡng nội dung và trình soạn thảo văn bản thường thì. Các định dạng diễn đạt API giống như OpenAPI / Swagger Specification sẽ tự động hóa quy trình xử lý tài liệu, giúp những nhóm thuận tiện hơn trong việc tạo và bảo dưỡng chúng .

Vậy thế nào là một tài liệu API tốt ?Một tài liệu API tốt được nhìn nhận trên rất nhiều góc nhìn, khó hoàn toàn có thể liệt kê hết ở đây. Tuy nhiên một điều chắc như đinh rằng, tài liệu API chỉ được coi là tốt khi nó gồm có cả hướng dẫn nhanh và hướng dẫn chi tiết cụ thể ; ngoài những, phải là tài liệu có tính tương tác cao để lập trình viên hoàn toàn có thể kiểm thử những lệnh gọi API .Tài liệu API cần phân phối ví dụ về mọi lệnh gọi, mọi tham số số và phản hồi cho mỗi lệnh gọi. Nó phải gồm có sample source code cho những ngôn từ được sử dụng phổ cập như Java, JavaScript, PHP và Python. Đồng thời, tài liệu phải phân phối lý giải cho từng API request và những ví dụ về message lỗi .

API Specification

API specification là một thuật ngữ thường được sử dụng sửa chữa thay thế lẫn nhau với API definition. Mặc dù hai thuật ngữ này có nhiều điểm tương đương nhưng trong thực tiễn chúng là những thực thể khác nhau .API specification phân phối sự hiểu biết thoáng đãng về cách một API hoạt động giải trí và cách API link với những API khác. Nó lý giải cách hoạt động giải trí của API và tác dụng mong đợi khi sử dụng API .Tài liệu đặc tả API gồm có nhiều đối tượng người dùng API, giá trị và tham số, cách những đối tượng người dùng được gọi và công dụng của mỗi đối tượng người tiêu dùng. Ngoài ra, tài liệu đặc tả API cũng cho thấy những mối quan hệ giữa những đối tượng người dùng và cách mỗi đối tượng người tiêu dùng hoàn toàn có thể được sử dụng .

API Definition

API definition tựa như như API specification ở chỗ nó phân phối sự hiểu biết về cách một API được tổ chức triển khai và cách API hoạt động giải trí. Tuy nhiên, API definition hướng đến việc sử dụng API của thiết bị thay vì việc sử dụng API của con người – những lập trình viên .Tài liệu định nghĩa API phân phối thông tin về phương pháp hoạt động giải trí của API, cách nó link với những API khác và hiệu quả mong đợi ở định dạng mà máy móc thiết bị hoàn toàn có thể đọc được. Nó tập trung chuyên sâu vào việc định nghĩa API và phác thảo cấu trúc của API .Tài liệu này được sử dụng làm cơ sở cho những công cụ tự động hóa như tự động hóa tạo tài liệu API ( SwaggerHub và Swagger Inspector ), code samples và SDK ( REST United và SwaggerHub ) .

Sự khác biệt giữa API Documentation, Specification, và Definition

Tài liệu API, đặc tả API và định nghĩa API đều có tương quan với nhau, nhưng chúng là những thực thể khác nhau. Và mỗi loại tài liệu đều Giao hàng một mục tiêu quan trọng khác nhau .Tài liệu API cho những nhà tăng trưởng và những người sử dụng API khác biết cách sử dụng API .Tài liệu đặc tả API phân phối sự hiểu biết thoáng đãng về công dụng của API và tác dụng mong đợi. Đặc điểm kỹ thuật đa phần là về phong cách thiết kế của API hoặc triết lý của API. Thiết kế và tính năng của API là những yếu tố chính khi chọn tích hợp API với một ứng dụng .Và ở đầu cuối, tài liệu định nghĩa API hướng đến việc sử dụng API của thiết bị máy móc, cung ứng định dạng mà thiết bị đó hoàn toàn có thể đọc được để sử dụng bởi những công cụ tự động hóa như tài liệu API tự động hóa ( automatic API documentation ) và trình tạo SDK tự động hóa ( SDK generators ) .

Hiểu sâu hơn về API Document

Tầm quan trọng của API Document

Một điều mê hoặc là những lập trình viên thường ít chú ý quan tâm đến tài liệu hướng dẫn ( API document ) khi chạy code. Trên thực tiễn, việc tiến hành code còn thuận tiện hơn rất nhiều so với việc viết một tài liệu API tốt .API document ảnh hưởng tác động trực tiếp tới việc tích hợp và sử dụng API. Sản phẩm của bạn hoàn toàn có thể có công dụng tốt nhất, nhưng sẽ không có ai dùng nếu họ không biết cách sử dụng như thế nào .Có thể nói, API document là nền tảng giúp lập trình viên có thưởng thức tốt .

Swagger là gì?

Swagger là một tool được cho phép diễn đạt cấu trúc của những API để máy móc hoàn toàn có thể đọc chúng. Bằng cách đọc cấu trúc API, Swagger hoàn toàn có thể tự động hóa tạo ra một tài liệu API đẹp và có tính tương tác .Ngoài ra, Swagger cũng hoàn toàn có thể tự động hóa tạo ra thư viện người mua cũng như kiểm tra tự động hóa ( automated testing ) bằng cách nhu yếu API trả lại một YAML hoặc JSON chứa miêu tả cụ thể về hàng loạt API. Tệp này về cơ bản là một list tài nguyên API tuân theo đặc thù kỹ thuật OpenAPI, trong đó gồm có những thông tin như :

API hỗ trợ các hoạt động gì?
API có những tham số nào? Trả về những gì?
API có cần authorization nào không?
Điều khoản, thông tin liên hệ và giấy phép sử dụng API

Có thể tạo Swagger specs theo cách bằng tay thủ công hoặc tạo tự động từ những chú thích trong mã nguồn. Kiểm tra swagger.io/open-source-integrations để nắm được list những công cụ được cho phép tạo Swagger từ code .

Cấu trúc cơ bản của Swagger Specs

Định nghĩa Swagger hoàn toàn có thể được viết bằng JSON hoặc YAML. Phần dưới đây sẽ lấy những ví dụ về YAML, tương tự như cho JSON .Một Swagger specification mẫu viết bằng YAML sẽ như sau :

Metadata

Xem thêm: Node là gì? Kiến thức cần biết về Node của Bitcoin và Blockchain

Mọi thông số kỹ thuật kỹ thuật của Swagger đều mở màn với phiên bản Swagger, trong đó 2.0 là phiên bản mới nhất .Phiên bản Swagger xác lập cấu trúc toàn diện và tổng thể của thông số kỹ thuật kỹ thuật API – gồm có những nội dung gì và diễn đạt những nội dung đó thế nào .

Sau đó, cần chỉ định API info (thông tin API), gồm title (tiêu đề), description (mô tả tùy chọn) và version (phiên bản API, không phải phiên bản Swagger).

version có thể là một chuỗi ngẫu nhiên. Chúng ta có thể sử dụng major.minor.patch hoặc định dạng tùy ý như 1.0-beta hoặc 2016.11.15.

descriptioncó thể đa dòng và hỗ trợ GitHub Flavored Markdown để trình bày văn bản đa dạng thức.

info cũng hỗ trợ các nội dung khác như thông tin liên hệ, giấy phép…

Base URL

Base URL cho tất cả các lệnh gọi API đều sử dụngschemes,host và basePath.

Mỗi một đường dẫn API ( API path ) đều tương quan đến base URL, ví dụ / users thực ra chính là https://api.example.com/v1/users .

Consumes, Produces

Consumes và Produces xác lập những loại MiME được API tương hỗ .

Paths

Phầnpaths xác định các endpoint (thao tác) riêng lẻ trong API và các phương thức HTTP được hỗ trợ bởi các endpoint này.

Ví dụ, GET / users hoàn toàn có thể được diễn đạt như sau :

Parameters

Các thao tác có thể có các tham số được pass qua đường dẫn URL(/users/{userId}), chuỗi truy vấn (/users?role=admin), tiêu đề (X-CustomHeader: Value) và nội dung yêu cầu.

Responses

Đối với mỗi thao tác, chúng ta có thể xác định các mã trạng thái có thể có, chẳng hạn như 200 OK hoặc 404 Not Found và schema của nội dung phản hồi.

Lược đồ có thể được xác định inline (nội tuyến) hoặc tham chiếu từ định nghĩa bên ngoài thông qua $ref. Ngoài ra, chúng ta cũng có thể cung cấp các phản hồi mẫu (example responses) cho từng loại nội dung.

Input and Output

Phần definitions cho phép định nghĩa cấu trúc dữ liệu chung được sử dụng trong API. Cấu trúc dữ liệu này có thể được tham chiếu thông qua $ref bất cứ khi nào cần schema cho cả nội dung yêu cầu (request body) và nội dung phản hồi (response body).

Ví dụ, với đối tượng người tiêu dùng JSON này :