Custom request example, response example asp.net core api

Phút ban đầu.

• Mình tạo một project asp.net core api hoàn toàn chiếu mới

• Thêm UseSwaggerUI để hiển thị thông tin api

• Trong file Startup.cs

• Thêm vào ConfigureServices

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "Weather Forecast API", Version = "v1" });
            });

• Thêm vào Configure

            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "Weather Forecast API V1");
            });

• Tổng quan file Startup.cs

• Để thêm được 2 đoạn trên các bạn thêm hai packages man này nhé.

 <ItemGroup>
  <PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="6.1.1" />
  <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="6.1.1" />
  </ItemGroup>

• File project .csproj

• Mình thêm 2 class SomeRequest ví dụ cho các request và SomeResponse ví dụ cho response trả về của api

       public class SomeRequest
       {
           public int Id { get; set; }
       }

     public class SomeResponse
     {
         public int Id { get; set; }
         public string Name { get; set; }
         public string Age { get; set; }
     }

• Thêm 1 api POST trong controller WeatherForecastController mặc định để làm ví dụ nhé. (tìm hiểm thêm về ProducesResponseType )

        [HttpPost]
        [ProducesResponseType(typeof(SomeResponse), (int)HttpStatusCode.OK)]
        public ActionResult<SomeResponse> Post([FromBody] SomeRequest req)
        {
            return Ok();
        }

• Rồi chạy thử lên thôi. Trước khi chạy trong file launchSettings.json các bạn trỏ launchUrl thành swagger/index.html nhé. Để khi run thì launch Url là trang SwaggerUI luôn cho dễ nhìn

• Kết quả

• Các bạn có thể thấy phần body example vs response example đang tự động gen ra giá trị mặc định của property.
• Để thuận tiện cho việc mô tả chính xác nhất api trong swagger thì chúng ta có thể custom các example này (rất đơn giản thôi ).

Nào!

1. Thêm package vào file project .csproj ở trên

 <PackageReference Include="Swashbuckle.AspNetCore.Filters" Version="7.0.2" />

2. Trong các class request hoặc response. Kế thừa IExamplesProvider<T> và implement interface nhé.

• Ví dụ trong class SomeResponse

    public class SomeResponse : IExamplesProvider<SomeResponse>
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public int Age { get; set; }

        public SomeResponse GetExamples()
        {
            return new SomeResponse
            {
                Id = 10,
                Name = "Peter Packer",
                Age = 16
            };
        }
    }

3. Trong starup.cs Thêm vào ConfigureServices services.AddSwaggerExamplesFromAssemblyOf<SomeRequest>(); và c.ExampleFilters(); trong lúc sử dụng middleware AddSwaggerGen nhé

• Các bạn đừng lo lắng khi có nhiều class kế thừa interface IExamplesProvider<T> mà trong startup chỉ trỏ tới mỗi SomeRequest, còn các class khác thì sao ???. Class SomeRequest đã kế thừa IExamplesProvider<T> thì mặc định là cái middleware này được dùng rồi nhé =))

4. Chạy thử thôi

• Kết quả

Tổng kết.

• Mặc dù là một phần khá đơn giản nhưng việc custom example cho request và respone cũng rất là xịn phải k :v.
• Đặc biệt với những bạn thích mô tả mọi thứ một cách tỉ mỉ và chính xác như thằng bạn mình.
• Các bạn có thể xem source code này ở Github mk nhé