Đối với d&acirc;n c&ocirc;ng nghệ, Swagger l&agrave; một kh&aacute;i niệm quen thuộc v&agrave; đ&atilde; được nhiều lập tr&igrave;nh vi&ecirc;n sử dụng. Tuy nhi&ecirc;n, với những người kh&ocirc;ng l&agrave;m trong ng&agrave;nh n&agrave;y muốn t&igrave;m hiểu th&ecirc;m th&igrave; rất dễ bị nhầm lẫn. B&agrave;i viết dưới đ&acirc;y của <a title="Tek4.vn" href="https://tek4.vn/">Tek4.vn</a> sẽ tổng hợp cho bạn những kiến thức cơ bản nhất về Swagger. Từ đ&oacute; gi&uacute;p bạn trả lời cho c&acirc;u hỏi Swagger l&agrave; g&igrave;, c&aacute;c hỗ trợ m&agrave; n&oacute; mang lại v&agrave; cấu tr&uacute;c c&agrave;i đặt như thế n&agrave;o.&nbsp;
<h2>Swagger l&agrave; g&igrave;?</h2>
<a href="https://tek4.vn/swagger-la-gi">Swagger</a> l&agrave; một bộ c&ocirc;ng cụ m&atilde; nguồn mở dựa v&agrave;o REST để đơn giản h&oacute;a qu&aacute; tr&igrave;nh viết c&aacute;c API nhờ chỉ định c&aacute;c ti&ecirc;u chuẩn. Đồng thời Swagger cũng cung cấp c&aacute;c c&ocirc;ng cụ cần thiết nhằm hỗ trợ viết được c&aacute;c API đẹp, an to&agrave;n, hiệu quả v&agrave; c&oacute; khả năng mở rộng cao. C&ocirc;ng cụ n&agrave;y gi&uacute;p bạn thiết kế, tạo dựng c&aacute;c t&agrave;i liệu cũng như sử dụng Rest APIs một c&aacute;ch hiệu quả hơn.&nbsp;
<img style="width: 700px; display: block; margin-left: auto; margin-right: auto;" title="Swagger l&agrave; một bộ c&ocirc;ng cụ d&agrave;nh cho nh&agrave; ph&aacute;t triển API từ Phần mềm SmartBear v&agrave; l&agrave; một đặc điểm kỹ thuật cũ m&agrave; Đặc điểm kỹ thuật OpenAPI dựa tr&ecirc;n đ&oacute;" src="https://tek4.vn/public_files/9b0a7327-053e-4457-b427-4b7fdfb439a5" alt="Swagger_UI" />
<h2>Swagger hỗ trợ g&igrave; trong việc viết API?</h2>
Trong qu&aacute; tr&igrave;nh viết API, Swagger sẽ hỗ trợ bạn chuẩn h&oacute;a to&agrave;n bộ quy tr&igrave;nh. Nếu bạn l&agrave; một Developer, bạn cần biết c&aacute;ch x&acirc;y dựng v&agrave; chuẩn ho&aacute; API ngay từ khi bắt đầu viết. Swagger sẽ gi&uacute;p bạn t&igrave;m ra nhiều &yacute; tưởng ngay từ giai đoạn đầu của qu&aacute; tr&igrave;nh viết phần mềm. Do đ&oacute;, c&aacute;c lập tr&igrave;nh vi&ecirc;n sẽ tiết kiệm nhiều thời gian t&aacute;i cấu tr&uacute;c m&atilde; hiệu quả nhờ những t&iacute;nh năng vượt trội của Swagger.&nbsp;
<h2>Cấu tr&uacute;c của một Swagger l&agrave; g&igrave;?</h2>
Để ứng dụng hiệu quả trong từng qu&aacute; tr&igrave;nh viết API cụ thể, c&aacute;c lập tr&igrave;nh vi&ecirc;n cần hiểu r&otilde; về cấu tr&uacute;c cơ bản của một Swagger. Một Swagger cơ bản c&oacute; 4 phần ch&iacute;nh dưới đ&acirc;y.&nbsp;
<ul>
<li style="font-weight: 400;" aria-level="1">Metadata hay Info: Chức năng ch&iacute;nh của Metadata hoặc Info l&agrave; hỗ trợ đưa ra c&aacute;c từ kho&aacute; về th&ocirc;ng tin li&ecirc;n lạc, chứng chỉ, điều khoản sử dụng. Nh&igrave;n chung, mỗi Open API Specifications khi được sử dụng đều bắt đầu bằng từ kho&aacute; &ldquo;Open API&rdquo; với mục đ&iacute;ch khai b&aacute;o t&ecirc;n của phi&ecirc;n bản đ&oacute;. Phi&ecirc;n bản được sử dụng sẽ c&oacute; &yacute; nghĩa đặc biệt trong việc định nghĩa lại tất cả cấu tr&uacute;c của API. Tại phần Info của Swagger sẽ c&oacute; đầy đủ th&ocirc;ng tin cơ bản nhất về API như ti&ecirc;u đề, m&ocirc; tả v&agrave; c&aacute;c phi&ecirc;n bản ch&iacute;nh. Trong đ&oacute;:&nbsp;</li>
</ul>
<ul>
<li style="font-weight: 400;" aria-level="1">Ti&ecirc;u đề (title) l&agrave; t&ecirc;n m&agrave; lập tr&igrave;nh vi&ecirc;n đặt cho API của m&igrave;nh.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">M&ocirc; tả (Description) l&agrave; c&aacute;c th&ocirc;ng tin chi tiết về API, xuất hiện ở nhiều mặt cụ thể kh&aacute;c nhau. Từ m&ocirc; tả n&agrave;y, lập tr&igrave;nh vi&ecirc;n c&oacute; thể viết th&agrave;nh nhiều d&ograve;ng v&agrave; sử dụng c&uacute; ph&aacute;p hỗ trợ (markdown) trong trường hợp qu&aacute; d&agrave;i.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">C&aacute;c phi&ecirc;n bản (versions) l&agrave; c&aacute;c phi&ecirc;n bản được sử dụng trong qu&aacute; tr&igrave;nh tạo dựng API của bạn.&nbsp;</li>
</ul>
<ul>
<li style="font-weight: 400;" aria-level="1">Servers: Muốn chạy thử c&aacute;c API, bạn cần c&oacute; một đường dẫn li&ecirc;n quan tới Servers. Đ&acirc;y l&agrave; phần tạo ra đường dẫn cụ thể của servers v&agrave; việc định nghĩa một hay nhiều servers kh&aacute;c nhau sẽ t&ugrave;y thuộc v&agrave;o quyết định của lập tr&igrave;nh vi&ecirc;n.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">Paths l&agrave; phần trọng t&acirc;m nhất của một API. Nhiệm vụ của c&aacute;c lập tr&igrave;nh vi&ecirc;n l&agrave; định nghĩa c&aacute;c Paths xuất hiện hay c&aacute;c phương thức, tham số cụ thể tồn tại trong API. Bạn cần ch&uacute; &yacute; c&aacute;c vấn đề dưới đ&acirc;y trong phần Paths của Swagger:&nbsp;</li>
</ul>
<ul>
<li style="font-weight: 400;" aria-level="1">Từ kho&aacute; bắt buộc được sử dụng khi bắt đầu phần n&agrave;y l&agrave; &ldquo;Paths&rdquo;.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">C&aacute;c th&agrave;nh phần c&oacute; trong API như users,...&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">Tiếp đ&oacute; l&agrave; c&aacute;c phương thức như Get, Post, Delete,... được sử dụng trong API.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">C&aacute;c tham số được th&ecirc;m v&agrave;o trong API được gọi l&agrave; Parameters. C&aacute;c Deve c&oacute; thể set c&aacute;c tham số required thực hiện việc m&ocirc; tả hoặc validate cho c&aacute;c tham số n&agrave;y. Hơn nữa, điểm đặc biệt của Paths l&agrave; c&aacute;c lập tr&igrave;nh vi&ecirc;n c&oacute; thể chỉ định một model bất kỳ với mục đ&iacute;ch định nghĩa c&aacute;c tham số đ&oacute; hiệu quả hơn.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">Response hay c&ograve;n được gọi l&agrave; trả về của Server: Phần trả về n&agrave;y c&oacute; thể được thực hiện việc định nghĩa cho c&aacute;c HTTP code m&agrave; người d&ugrave;ng nhận được như 200, 404,... Đi k&egrave;m với c&aacute;c HTTP code n&agrave;y l&agrave; c&aacute;c d&ograve;ng m&ocirc; tả xuất hiện với từng trường hợp cụ thể.&nbsp;</li>
</ul>
Ngo&agrave;i ra, trong phần Paths n&agrave;y, c&aacute;c parameters sẽ sở hữu kh&aacute; nhiều loại khai b&aacute;o kh&aacute;c nhau đứng sau từ kho&aacute; &ldquo;in&rdquo; m&agrave; lập tr&igrave;nh vi&ecirc;n cần ch&uacute; &yacute;:
<ul>
<li style="font-weight: 400;" aria-level="1">In body hỗ trợ người d&ugrave;ng c&oacute; một kh&ocirc;ng gian để tạo ra dữ liệu đầu v&agrave;o, nhập c&aacute;c dữ liệu về c&aacute;c y&ecirc;u cầu cơ bản trong đ&oacute;.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">In formData gi&uacute;p người d&ugrave;ng tạo input được chỉ định trước để nhập dữ liệu y&ecirc;u cầu theo từng miền định sẵn.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">In path được d&ugrave;ng trong qu&aacute; tr&igrave;nh tạo lập input trong gi&aacute; trị nhằm khai b&aacute;o c&aacute;c routers (ID).&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">In query d&ugrave;ng để tạo input nhập v&agrave;o c&aacute;c gi&aacute; trị thống k&ecirc; từ c&aacute;c miền định sẵn trong qu&aacute; tr&igrave;nh gửi query request.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">In header được d&ugrave;ng để khai b&aacute;o c&aacute;c gi&aacute; trị trong header của y&ecirc;u cầu bạn cần thực hiện để truyền tải.&nbsp;</li>
</ul>
<ul>
<li style="font-weight: 400;" aria-level="1">Schema tương tự như một model, được thực hiện phần khai b&aacute;o th&ocirc;ng qua sử dụng từ kho&aacute; component v&agrave; schemas. Trong phần n&agrave;y c&oacute; một số vấn đề bạn cần quan t&acirc;m l&agrave;:&nbsp;</li>
</ul>
<ul>
<li style="font-weight: 400;" aria-level="1">T&ecirc;n của model hoặc users l&agrave; t&ecirc;n của loại tham số đầu ti&ecirc;n m&agrave; bạn sử dụng.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">Tiếp đ&oacute; l&agrave; định dạng được d&ugrave;ng hay object.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">Cuối c&ugrave;ng l&agrave; c&aacute;c th&ocirc;ng tin về thuộc t&iacute;nh ch&iacute;nh.&nbsp;</li>
</ul>
<h2>Swagger UI l&agrave; g&igrave;?</h2>
Swagger UI l&agrave; một c&ocirc;ng cụ cho ph&eacute;p Developer hoặc người d&ugrave;ng cuối c&oacute; thể h&igrave;nh dung v&agrave; tương t&aacute;c c&ugrave;ng c&aacute;c t&agrave;i nguy&ecirc;n API của dự &aacute;n. C&ocirc;ng cụ n&agrave;y sẽ tự động tạo ra c&aacute;c t&agrave;i liệu API từ một file config Swagger. Giao diện trực quan hơn, khả năng triển khai trở n&ecirc;n đơn giản v&agrave; dễ d&agrave;ng hơn cho ph&iacute;a c&aacute;c client đăng nhập l&agrave; ưu điểm của Swagger UI. V&igrave; vậy, n&oacute; l&agrave; c&ocirc;ng cụ c&oacute; tần suất sử dụng v&agrave; ứng dụng phổ biến nhất trong số c&aacute;c phi&ecirc;n bản Swagger hiện nay. Đồng thời, n&oacute; cũng l&agrave; c&ocirc;ng cụ sở hữu c&aacute;c chức năng ph&ugrave; hợp khi ứng dụng v&agrave;o API.&nbsp;
<h2>C&agrave;i đặt Swagger UI như thế n&agrave;o?</h2>
Để c&agrave;i đặt Swagger UI, bạn cần thực hiện c&aacute;c bước cơ bản dưới đ&acirc;y:&nbsp;
<ul>
<li style="font-weight: 400;" aria-level="1">Bước 1: Tải về thư viện của Swagger UI bằng c&aacute;ch đăng nhập v&agrave;o trang chủ https://swagger.io/. Chuyển tới mục tải về (download) thư viện Swagger UI để t&igrave;m hướng dẫn clone từ Github repository. Sau đ&oacute;, copy thư mục dist xuất hiện trong dự &aacute;n đ&oacute; v&agrave; d&aacute;n v&agrave;o dự &aacute;n của bạn. Lựa chọn Render file Index.html c&oacute; trong dist, nếu bạn chạy localhost:3000 tr&ecirc;n tr&igrave;nh duyệt, bạn sẽ nhận được một trang demo của Swagger UI.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">Bước 2: Cấu h&igrave;nh routes trỏ đường li&ecirc;n kết dẫn tới file index.html. Nếu bạn x&acirc;y dựng một ứng dụng Rail app v&agrave; thả to&agrave;n bộ thư viện v&agrave;o mục /public. Bạn cấu h&igrave;nh trong file routes.rb theo c&uacute; ph&aacute;p sau <code>&ldquo;get &ldquo;/swaggers&rdquo;, to: redirect(&ldquo;/swagger-ui/dist/index.html&rdquo;)</code>. L&uacute;c n&agrave;y, bạn sẽ được đưa tới file index.html ở tr&ecirc;n khi truy cập tới URL/swaggers.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">Bước 3: Tạo Config trong c&aacute;c cấu h&igrave;nh API. Thực tế, một file yaml trong Swagger c&oacute; c&aacute;c cấu tr&uacute;c như Open API, Info, Title, Version, Description. security, Paths v&agrave; Component. Ngo&agrave;i c&aacute;c phần n&agrave;y sẽ c&oacute; th&ecirc;m keyword kh&aacute;c m&agrave; bạn c&oacute; thể sử dụng tại trang document của Swagger. B&ecirc;n cạnh yaml, lập tr&igrave;nh vi&ecirc;n cũng c&oacute; thể viết config ở dưới dạng Jsol với Swagger. Tuy nhi&ecirc;n, nhiều chuy&ecirc;n gia nhận định Yaml l&agrave; định dạng tốt v&agrave; ph&ugrave; hợp nhất. Tiếp đ&oacute;, bạn chỉ cần tạo một file Yaml với cấu tr&uacute;c tương tự như Swagger UI demo trước đ&oacute;. Sau đ&oacute; lưu lại tệp v&agrave;o trong thư mục dist như ở bước 1.&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">Bước 4: Cập nhật lại đường dẫn URL của file config: Muốn sử dụng được Swagger, lập tr&igrave;nh vi&ecirc;n phải trỏ URL đến file Swagger vừa config trong file <code>Dist/index.html.&nbsp;</code></li>
<li style="font-weight: 400;" aria-level="1">Trong file <code>dist/index.html</code>, t&igrave;m đến đoạn cuối file, bạn sẽ thấy đoạn khai b&aacute;o <code>&ldquo;const ui = SwaggerUIBundle&rdquo; c&oacute; đoạn &ldquo;URL: https://petstore.swagger.io/v2/swagger.json&rdquo;.&nbsp;</code></li>
<li style="font-weight: 400;" aria-level="1">Sửa li&ecirc;n kết URL n&agrave;y th&agrave;nh URL trỏ tới file swagger.yaml vừa tạo ở bước 2. Lấy v&iacute; dụ đơn giản, khi file swagger.yaml của bạn đang nằm trong thư mục public/api_docs của Rails app, bạn c&oacute; thể thay đổi th&agrave;nh url: <code>&ldquo;/api_docs/swagger.yaml&rdquo;.</code>&nbsp;</li>
<li style="font-weight: 400;" aria-level="1">Cuối c&ugrave;ng l&agrave; truy cập lại v&agrave;o file swaggers để thấy kết quả. Sau đ&oacute;, lập tr&igrave;nh vi&ecirc;n c&oacute; thể th&ecirc;m v&agrave;o paths trong file swagger.yaml để ho&agrave;n th&agrave;nh API document cho dự &aacute;n của m&igrave;nh.&nbsp;</li>
</ul>
Kết&nbsp;
Tr&ecirc;n đ&acirc;y l&agrave; to&agrave;n bộ th&ocirc;ng tin m&agrave; tek4.vn muốn giải đ&aacute;p cho bạn đọc về thắc mắc Swagger l&agrave; g&igrave;. Hy vọng với những chia sẻ từ tek4.vn, bạn đọc c&oacute; thể hiểu hơn về cấu tr&uacute;c cũng như c&aacute;ch c&agrave;i đặt Swagger UI nhanh ch&oacute;ng, dễ d&agrave;ng.&nbsp;

Admin

Swagger là gì? Công cụ hỗ trợ viết document cho Resful API

Cùng tác giả

Admin

Có liên quan