Thiên Vũ
ASP.NET Core trong .NET 9 hợp lý hóa quy trình tạo tài liệu OpenAPI cho các điểm cuối API của bạn với hỗ trợ tích hợp mới cho việc tạo tài liệu OpenAPI. Tính năng mới này được thiết kế để đơn giản hóa quy trình phát triển và cải thiện việc tích hợp các định nghĩa OpenAPI trong các ứng dụng ASP.NET của bạn. Và việc áp dụng rộng rãi OpenAPI đã thúc đẩy một hệ sinh thái phong phú các công cụ và dịch vụ có thể giúp bạn xây dựng, kiểm tra và lập tài liệu cho API của mình hiệu quả hơn. Một số ví dụ là Swagger UI , trình tạo thư viện máy khách Kiota và Redoc , nhưng vẫn còn rất nhiều, rất nhiều nữa.
Tại sao lại là OpenAPI?
OpenAPI là một công cụ mạnh mẽ để xác định và ghi lại API HTTP. Nó cung cấp một cách chuẩn để mô tả các điểm cuối, định dạng yêu cầu và phản hồi, lược đồ xác thực và các chi tiết thiết yếu khác của API. Việc chuẩn hóa này giúp các nhà phát triển dễ hiểu và tương tác với API hơn, dẫn đến sự cộng tác tốt hơn và các ứng dụng mạnh mẽ hơn. Và
Ngoài ra, nhiều mô hình ngôn ngữ lớn (LLM) đã được đào tạo trên các tài liệu OpenAPI, cho phép chúng tự động tạo mã, trường hợp thử nghiệm và các hiện vật khác. Bằng cách tạo tài liệu OpenAPI cho API của bạn, bạn có thể tận dụng các LLM này để đẩy nhanh quá trình phát triển của mình.
Có gì mới trong .NET 9?
Với .NET 9, chúng tôi giới thiệu hỗ trợ tích hợp cho việc tạo tài liệu OpenAPI, cung cấp trải nghiệm tích hợp và liền mạch hơn cho các nhà phát triển .NET. Tính năng này có thể được sử dụng trong cả API tối thiểu và các ứng dụng dựa trên bộ điều khiển. Sau đây là một số điểm nổi bật chính:
- Hỗ trợ tạo tài liệu OpenAPI khi chạy và truy cập chúng thông qua điểm cuối trên ứng dụng hoặc tạo chúng khi biên dịch.
- Thuộc tính và phương pháp mở rộng để thêm siêu dữ liệu vào phương pháp API và dữ liệu.
- Hỗ trợ API “biến đổi” cho phép sửa đổi tài liệu được tạo theo nhiều cách khác nhau.
- Hỗ trợ tạo nhiều tài liệu OpenAPI từ một ứng dụng duy nhất.
- Tận dụng sự hỗ trợ của lược đồ JSON được cung cấp bởi System.Text.Json .
- Tương thích với AoT gốc khi sử dụng kết hợp với API tối thiểu.
Làm thế nào để bắt đầu
Bắt đầu với tính năng tạo tài liệu OpenAPI mới trong .NET 9 rất đơn giản. Sau đây là hướng dẫn nhanh giúp bạn bắt đầu.
Cập nhật lên .NET 9
Đảm bảo rằng dự án của bạn đang sử dụng .NET 9, được phát hành vào đầu tháng này. Bạn có thể tải xuống phiên bản mới nhất từ trang web chính thức .NET .
Nếu bạn đang thêm hỗ trợ OpenAPI vào một dự án hiện có, bạn sẽ cần cập nhật dự án của mình để hướng tới .NET 9. Có hướng dẫn di chuyển chi tiết cho việc này trong tài liệu ASP.NET Core .
Bật hỗ trợ OpenAPI
Nếu bạn đang bắt đầu một dự án mới, hỗ trợ OpenAPI đã được tích hợp sẵn trong webapimẫu .NET 9.
Để kích hoạt tài liệu OpenAPI trong một dự án hiện có, bạn chỉ cần thêm gói Microsoft.AspNetCore.OpenApi và thêm một vài dòng mã vào tệp ứng dụng chính của mình.
Bạn có thể thêm gói bằng dotnet add packagelệnh:
Sao chép
dotnet add package Microsoft.AspNetCore.OpenApi
Sau đó, trong Program.cstệp của bạn, bạn cần thêm các dịch vụ OpenAPI vào WebApplicationBuilder:
Sao chép
builder.Services.AddOpenApi();
Có nhiều tùy chọn cấu hình khác nhau có sẵn cho tính năng OpenAPI, chẳng hạn như đặt tiêu đề tài liệu, phiên bản và siêu dữ liệu khác. Bạn có thể tìm thêm thông tin về các tùy chọn này trong tài liệu ASP.NET Core .
Sau đó thêm điểm cuối vào ứng dụng của bạn để phục vụ tài liệu OpenAPI với MapOpenApiphương thức mở rộng, như thế này:
Sao chép
app.MapOpenApi();
Bây giờ bạn có thể chạy ứng dụng của mình và truy cập tài liệu OpenAPI được tạo tại /openapi/v1.jsonđiểm cuối.
Những gì bạn sẽ thấy ở đó là một tài liệu OpenAPI với các đường dẫn, hoạt động và lược đồ dựa trên mã cho ứng dụng của bạn, nhưng có thể không có các chi tiết quan trọng như mô tả và ví dụ. Để có được các thành phần này, bạn sẽ cần thêm siêu dữ liệu như mô tả trong phần tiếp theo.
Thêm siêu dữ liệu OpenAPI
Có thể thêm mô tả, thẻ, ví dụ và siêu dữ liệu khác vào phương thức API và dữ liệu của bạn để cung cấp ý nghĩa cho tài liệu OpenAPI được tạo. Siêu dữ liệu này có thể được thêm bằng cách sử dụng thuộc tính hoặc phương thức mở rộng.
Bạn có thể thêm tóm tắt và mô tả cho từng điểm cuối trong ứng dụng của mình bằng cách sử dụng các phương thức mở rộng WithSummaryvà WithDescription:
Sao chép
app.MapGet("/hello", () => "Hello, World!")
.WithSummary("Get a greeting")
.WithDescription("This endpoint returns a friendly greeting.");
Tóm tắt và mô tả điểm cuối rất quan trọng vì chúng cho người dùng (và LLM) biết những việc họ có thể thực hiện với API của bạn.
Bạn cũng có thể muốn nhóm các điểm cuối liên quan lại với nhau trong tài liệu và điều này thường được thực hiện bằng thẻ. Bạn có thể thêm thẻ vào các điểm cuối của mình bằng WithTagphương pháp mở rộng:
Sao chép
app.MapGet("/hello", () => "Hello, World!")
.WithTag("Greetings");
Khi một điểm cuối có tham số, điều quan trọng là phải bao gồm mô tả về từng tham số để giải thích ý nghĩa của tham số đó và cách điểm cuối sử dụng tham số đó. Sử dụng [Description]thuộc tính để thêm mô tả vào tham số:
Sao chép
Giải thích
app.MapGet("/hello/{name}", ( [Description("The name of the person to greet.")] string name ) => $"Hello, {name}!") .WithSummary("Get a personalized greeting") .WithDescription("This endpoint returns a personalized greeting.") .WithTag("Greetings");
Bạn cũng có thể sử dụng [Description]thuộc tính này để thêm mô tả vào các thuộc tính trong mô hình dữ liệu của mình:
Sao chép
Giải thích
public record Person { [Description("The person's name.")] public string Name { get; init; } [Description("The person's age.")] public int Age { get; init; } }
Có nhiều thuộc tính siêu dữ liệu khác để mô tả các tham số và thuộc tính, bao gồm [MaxLength], [Range], [RegularExpression], và [DefaultValue]. Lưu ý rằng trong các ứng dụng dựa trên bộ điều khiển, các thuộc tính này kích hoạt các xác thực được thực hiện trong quá trình liên kết mô hình, nhưng trong API Minimal, chúng chỉ được sử dụng để lập tài liệu.
Xem chủ đề Bao gồm siêu dữ liệu OpenAPI trong tài liệu để tìm hiểu thêm về cách thêm siêu dữ liệu vào phương thức API và dữ liệu của bạn.
Tùy chỉnh tài liệu của bạn
ASP.NET cũng cung cấp một cách để tùy chỉnh tài liệu OpenAPI được tạo bằng cách sử dụng "transformers", có thể hoạt động trên toàn bộ tài liệu, trên các hoạt động hoặc trên các lược đồ. Transformers là các lớp triển khai các giao diện IOpenApiDocumentTransformer, IOpenApiOperationTransformer, hoặc IOpenApiSchemaTransformer. Mỗi giao diện này có một phương thức async duy nhất nhận tài liệu, hoạt động hoặc lược đồ cần chuyển đổi cùng với một đối tượng ngữ cảnh cung cấp thông tin bổ sung. Tài liệu, hoạt động hoặc lược đồ OpenAPI được truyền cho một transformer là một đối tượng được gõ mạnh bằng cách sử dụng các kiểu từ không gian tên Microsoft.OpenApi.Models . Phương thức thực hiện chuyển đổi "tại chỗ" bằng cách sửa đổi đối tượng mà nó nhận được.
Các bộ biến đổi được thêm vào bằng configureOptionstham số đại biểu của lệnh AddOpenApigọi và có thể được chỉ định là một thể hiện của một lớp, là một lớp được kích hoạt bởi DI hoặc là một phương thức đại biểu.
Sao chép
Giải thích
builder.Services.AddOpenApi(options => { // document transformer added as an instance of a class options.AddDocumentTransformer(new MyDocumentTransformer()); // operation transformer added as a DI-activated class options.AddOperationTransformer<MyOperationTransformer>(); // schema transformer added as a delegate method options.AddSchemaTransformer((schema, context, cancellationToken) => Task.CompletedTask); });
Một ứng dụng của trình chuyển đổi tài liệu là sửa đổi các phần của tài liệu OpenAPI bên ngoài các phần pathsvà components.schemas. Ví dụ, bạn có thể thêm a contactvào infophần tử của tài liệu như thế này:
Sao chép
Giải thích
builder.Services.AddOpenApi(options => { options.AddDocumentTransformer((document, context, cancellationToken) => { document.Info.Contact = new OpenApiContact { Name = "Contoso Support", Email = "support@contoso.com" }; return Task.CompletedTask; } });
Bộ chuyển đổi hoạt động có thể được sử dụng để sửa đổi các hoạt động riêng lẻ trong tài liệu. Một bộ chuyển đổi hoạt động được gọi trên mọi hoạt động trong ứng dụng và nó có thể chọn sửa đổi hoạt động hoặc không. Ví dụ: bạn có thể thêm securityyêu cầu vào tất cả các hoạt động yêu cầu ủy quyền như thế này:
Sao chép
Giải thích
options.AddOperationTransformer((operation, context, cancellationToken) => { if (context.Description.ActionDescriptor.EndpointMetadata.OfType<IAuthorizeData>().Any()) { operation.Security = [new() { ["Bearer"] = [] }]; } return Task.CompletedTask; });
Có thể sử dụng bộ chuyển đổi lược đồ để sửa đổi lược đồ cho ứng dụng. Các lược đồ mô tả các thân yêu cầu hoặc phản hồi của các hoạt động. Các thuộc tính phức tạp trong một thân yêu cầu hoặc phản hồi có thể có lược đồ riêng. Có thể sử dụng bộ chuyển đổi lược đồ để sửa đổi bất kỳ hoặc tất cả các lược đồ này.
Điều quan trọng là phải biết rằng tất cả các bộ chuyển đổi, bao gồm cả bộ chuyển đổi lược đồ, đều được gọi trước khi lược đồ được chuyển đổi thành tham chiếu “$ref” — một quá trình được thảo luận trong phần tiếp theo.
Ví dụ sau đây cho thấy một trình chuyển đổi lược đồ đơn giản thiết lập formattrường decimalcho bất kỳ lược đồ nào biểu diễn giá trị C# decmial.
Sao chép
Giải thích
options.AddSchemaTransformer((schema, context, cancellationToken) => { if (context.JsonTypeInfo.Type == typeof(decimal)) { // default schema for decimal is just type: number. Add format: decimal schema.Format = "decimal"; } return Task.CompletedTask; });
Tùy chỉnh tái sử dụng lược đồ
Sau khi tất cả các bộ chuyển đổi đã được áp dụng, khung sẽ thực hiện một lần chuyển qua tài liệu, chuyển một số lược đồ nhất định sang components.schemasphần, thay thế chúng bằng $refcác tham chiếu đến lược đồ đã chuyển. Điều này làm giảm kích thước của tài liệu và giúp dễ đọc hơn.
Chi tiết về quá trình xử lý này hơi phức tạp và có thể thay đổi trong các phiên bản .NET tương lai, nhưng nhìn chung:
- Các lược đồ cho kiểu lớp/bản ghi/cấu trúc được thay thế bằng
$reflược đồcomponents.schemasnếu chúng xuất hiện nhiều hơn một lần trong tài liệu. - Các lược đồ cho các kiểu nguyên thủy và bộ sưu tập chuẩn được để "trong dòng".
- Các lược đồ cho kiểu enum luôn được thay thế bằng
$reflược đồ a trong tocomponents.schemas.
Thông thường tên của lược đồ components.schemaslà tên của kiểu lớp/bản ghi/cấu trúc, nhưng trong một số trường hợp phải sử dụng tên khác.
ASP.NET Core cho phép bạn tùy chỉnh lược đồ nào được thay thế bằng a $refthành lược đồ khi components.schemassử dụng CreateSchemaReferenceIdthuộc tính của OpenApiOptions. Thuộc tính này là một đại biểu lấy một JsonTypeInfođối tượng và trả về tên của lược đồ trong components.schemasđó nên được sử dụng cho loại đó. Khung cung cấp một triển khai mặc định của đại biểu này, OpenApiOptions.CreateDefaultSchemaReferenceId, sử dụng tên của loại, nhưng bạn có thể thay thế nó bằng triển khai của riêng bạn.
Là một ví dụ đơn giản về tùy chỉnh này, bạn có thể chọn luôn nội tuyến các lược đồ enum. Điều này được thực hiện bằng cách thiết lập CreateSchemaReferenceIdmột đại biểu luôn trả về nullcho các kiểu enum và nếu không thì trả về giá trị từ triển khai mặc định. Mã sau đây cho biết cách thực hiện điều này:
Sao chép
Giải thích
builder.Services.AddOpenApi(options => { // Always inline enum schemas options.CreateSchemaReferenceId = (type) => type.Type.IsEnum ? null : OpenApiOptions.CreateDefaultSchemaReferenceId(type); });
Tạo tài liệu OpenAPI tại thời điểm xây dựng
Một tính năng mà tôi nghĩ nhiều nhà phát triển .NET sẽ thấy hấp dẫn là tùy chọn tạo tài liệu OpenAPI tại thời điểm xây dựng. Việc tạo tài liệu OpenAPI như một phần của quy trình xây dựng giúp tích hợp dễ dàng hơn nhiều với các công cụ trong quy trình phát triển cục bộ hoặc quy trình CI của bạn. Ví dụ: bạn có thể chạy linter trên tài liệu đã tạo để đảm bảo nó đáp ứng các tiêu chuẩn của tổ chức bạn hoặc bạn có thể sử dụng tài liệu để tạo mã máy khách hoặc các bài kiểm tra.
Việc tạo tài liệu OpenAPI tại thời điểm xây dựng rất đơn giản. Chỉ cần thêm Microsoft.Extensions.ApiDescription.Servergói vào dự án của bạn. Theo mặc định, tài liệu OpenAPI được tạo vào thư objmục của dự án, nhưng bạn có thể tùy chỉnh vị trí của tài liệu được tạo bằng thuộc OpenApiDocumentsDirectorytính. Ví dụ, để tạo tài liệu vào thư mục gốc của dự án, hãy thêm nội dung sau vào tệp dự án của bạn:
Sao chép
<PropertyGroup>
<OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory>
</PropertyGroup>
Lưu ý rằng việc tạo tài liệu OpenAPI theo thời gian xây dựng hoạt động bằng cách khởi chạy điểm vào của ứng dụng với một triển khai máy chủ trơ. Điều này cho phép khung kết hợp siêu dữ liệu chỉ khả dụng khi chạy, nhưng có thể yêu cầu một số thay đổi trong ứng dụng của bạn để hoạt động bình thường trong một số tình huống xây dựng nhất định.
Xem chủ đề Tạo OpenAPI tại thời điểm xây dựng trong tài liệu để biết thêm thông tin.
Tính năng tạo tài liệu OpenAPI mới trong .NET 9 cung cấp cho các nhà phát triển một con đường mới để tạo và duy trì tài liệu API cho các ứng dụng ASP.NET của họ. Bằng cách tích hợp chức năng này trực tiếp vào ASP.NET Core, các nhà phát triển hiện có thể tạo tài liệu OpenAPI tại thời điểm xây dựng hoặc thời điểm chạy, tùy chỉnh chúng khi cần và đảm bảo chúng đồng bộ với mã của họ. Và trong các ứng dụng API Minimal, tính năng này hoàn toàn tương thích với biên dịch AoT gốc.
Chúng tôi rất mong nhận được phản hồi của bạn về tính năng mới này. Vui lòng dùng thử và cho chúng tôi biết suy nghĩ của bạn.
