Làm cách nào để sử dụng Swagger trong Ứng dụng API Web?
Trong bài viết này, tôi sẽ thảo luận về cách sử dụng Swagger trong Ứng dụng API WEB để ghi lại và kiểm tra các dịch vụ API Web đầy đủ. Vui lòng đọc bài viết trước của chúng tôi, nơi chúng tôi đã thảo luận Cách tạo ứng dụng API Web ASP.NET từng bước trước khi tiếp tục bài viết này vì chúng tôi sẽ làm việc với cùng một ví dụ. Là một phần của bài viết này, chúng tôi sẽ thảo luận về các gợi ý sau.
- Swagger là gì?
- Làm cách nào để thêm Swagger vào ứng dụng API Web?
- Làm cách nào để định cấu hình Swagger trong ASP.NET Web API?
- Hiểu giao diện người dùng Swagger.
- Làm cách nào để kích hoạt Swagger để sử dụng các nhận xét XML?
Swagger là gì?
Swagger là một đại diện đơn giản nhưng mạnh mẽ của API RESTful. Ngày nay, hầu hết các nhà phát triển đang sử dụng Swagger trong hầu hết mọi ngôn ngữ lập trình và môi trường triển khai hiện đại để làm tài liệu. Với API Web hỗ trợ Swagger, bạn sẽ nhận được tài liệu tương tác, tạo SDK khách hàng cũng như khả năng khám phá.
Làm cách nào để thêm Swagger vào dự án API Web?
Để thêm Swagger vào dự án ASP.NET Web API của bạn, bạn cần cài đặt một dự án nguồn mở có tên Swashbuckle thông qua NuGet như hiển thị bên dưới.
Khi gói được cài đặt thành công, hãy điều hướng đến thư mục App_Start trong Solution Explorer. Bạn sẽ tìm thấy một tệp mới có tên SwaggerConfig.cs . Đây là tệp nơi Swagger được bật và mọi tùy chọn cấu hình nên được đặt ở đây.
Làm cách nào để cấu hình Swagger trong ứng dụng API Web ASP.NET?
Để bật Swagger và Swagger UI, hãy sửa đổi lớp SwaggerConfig như bên dưới
- namespace FirstWebAPIDemo
- {
- public class SwaggerConfig
- {
- public static void Register()
- {
- var thisAssembly = typeof(SwaggerConfig).Assembly;
- GlobalConfiguration.Configuration
- .EnableSwagger(c => c.SingleApiVersion("v1", "First WEB API Demo"))
- .EnableSwaggerUi();
- }
- }
- }
Bắt đầu một phiên gỡ lỗi mới bằng cách nhấn phím F5 và điều hướng đến http: // localhost: [PORT_NUM] / swagger và sau đó bạn sẽ thấy các trang trợ giúp cho API của mình.
Đồng ý. Thật tuyệt. Bây giờ hãy mở rộng một API và sau đó nhấp vào trên Hãy dùng thử! Nút nút sẽ thực hiện cuộc gọi đến API cụ thể đó và trả về kết quả như trong hình bên dưới.
Ở đây bấm vào nút Dùng thử sẽ hiển thị kết quả như hiển thị bên dưới.
Theo cùng một cách, bạn có thể kiểm tra tất cả các phương pháp khác.
Làm cách nào để kích hoạt Swagger để sử dụng Nhận xét XML trong Ứng dụng API Web ASP.NET?
Đến bây giờ, chúng tôi sử dụng cấu hình tối thiểu để bắt đầu. Nhưng bây giờ chúng tôi sẽ thêm nhiều tùy chỉnh. Chúng tôi có thể yêu cầu Swashbuckle sử dụng các nhận xét XML tùy chỉnh của mình để thêm chi tiết về API của chúng tôi vào siêu dữ liệu Swagger.
Trước tiên, chúng ta cần cho phép tạo tệp tài liệu XML trong quá trình xây dựng. Trong Solution Explorer, nhấp chuột phải vào dự án API Web và nhấp vào Thuộc tính. Nhấp vào tab Build và điều hướng đến đầu ra. Hãy chắc chắn rằng tệp tài liệu XML đã được kiểm tra. Bạn có thể để đường dẫn tập tin mặc định. Trong trường hợp của chúng tôi, bin \ FirstWebAPIDemo.XML của nó như được hiển thị bên dưới
Tiếp theo, chúng ta cần nói với Swashbuckle để đưa các nhận xét XML của chúng ta vào siêu dữ liệu Swagger. Để làm điều này, chúng ta cần thêm dòng sau vào SwaggerConfig.cs . Đảm bảo thay đổi đường dẫn tệp thành đường dẫn của tệp tài liệu XML của bạn.
c.IncludeXmlComments (string.Format (@ Lâm {0} \ bin \ FirstWebAPIDemo.XML,, System.AppDomain.CienDomain.BaseDirectory));
Cấu hình, cho đến nay
- namespace FirstWebAPIDemo
- {
- public class SwaggerConfig
- {
- public static void Register()
- {
- var thisAssembly = typeof(SwaggerConfig).Assembly;
- GlobalConfiguration.Configuration
- .EnableSwagger(c =>
- {
- c.SingleApiVersion("v1", "First WEB API Demo");
- c.IncludeXmlComments(string.Format(@"{0}\bin\FirstWebAPIDemo.XML",
- System.AppDomain.CurrentDomain.BaseDirectory));
- })
- .EnableSwaggerUi();
- }
- }
- }
Hãy thêm một số tài liệu XML vào các phương thức API của chúng tôi như được hiển thị bên dưới. Ở đây chúng tôi đang thêm Tài liệu XML vào phương thức get. Sửa đổi phương thức Get như hình bên dưới.
- /// <summary>
- /// Get All the Values
- /// </summary>
- /// <remarks>
- /// Get All the String Values
- /// </remarks>
- /// <returns></returns>
- public IEnumerable<string> Get()
- {
- return new string[] { "value1", "value2" };
- }
Chạy ứng dụng và điều hướng trở lại / swagger . Bạn sẽ thấy thêm chi tiết được thêm vào tài liệu API của mình như được hiển thị bên dưới.
Trong bài viết tiếp theo, tôi sẽ thảo luận về cách sử dụng Fiddler để kiểm tra ASP.NET WEB API Services. Ở đây, trong bài viết này, tôi cố gắng giải thích cách sử dụng Swagger trong Ứng dụng API Web để ghi lại và kiểm tra Dịch vụ API Web ASP.NET. Tôi hy vọng bây giờ bạn đã hiểu rõ về cách sử dụng Swagger trong Ứng dụng API Web ASP.NET.
إرسال تعليق