Блог

Это может быть нетривиальный вопрос, но, используя C# (.Net Core 3.1), я создаю профили swagger с помощью Swashbuckle.

Одна из моделей (внешний поставщик услуг) содержит поле формы object[] , которое может принимать два разных типа объектов:

 Object1 {
   Field1
   Field2
}

Object2 {
   Field1
   Field2
}
 

Можно ли как-то задокументировать это в чванстве? По умолчанию object[] в Swagger будет показано следующее:

 MyObject [
    null
]
 

В идеале я хотел бы показать примеры того null , чем на самом деле может быть этот объект.

Возможно ли это?

Пожалуйста, обратите внимание, что рассматриваемая модель предоставляется внешней службой, я просто пытаюсь выяснить, можно ли предоставить какую-либо значимую документацию в Swagger для клиентов, использующих приложение, в создании которого я участвую.

Swagger-лучший способ показать документацию, теперь, чтобы получить классы моделей возвращаемых типов, я бы предложил вам добавить атрибут «ProducesResponseType» поверх вашего метода. Вот как будет выглядеть Startup.cs.

 public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {

        services.AddControllers();
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo
            {
                Title = "Your Api name",
                Version = "v1",
                Description = "A simple example ASP.NET Core Web API",
                TermsOfService = new Uri("https://example.com/terms"),
                Contact = new OpenApiContact
                {
                    Name = "Custom Name",
                    Email = string.Empty,
                    Url = new Uri("https://linkedin.com/sampleurl"),
                },
                License = new OpenApiLicense
                {
                    Name = "Use under LICX",
                    Url = new Uri("https://example.com/license"),
                }
            });

            // Set the comments path for the Swagger JSON and UI.
            var xmlFile = $"{Assembly.GetEntryAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
            c.IncludeXmlComments(xmlPath);
        });
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();

        }
        app.UseSwagger(c =>
        {
            c.SerializeAsV2 = true;
        });

        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your Api name");
        });

        app.UseHttpsRedirection();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
 

Теперь, когда вы настроили swagger в файле startup.cs, пришло время использовать их в своем контроллере.

 [Route("api/[controller]")]
[ApiController]
public class SampleController : ControllerBase
{
    /// <summary>
    /// Sample Summary
    /// </summary>
    /// <param name="param1">About Param 1</param>
    /// <param name="param2">About Param 2</param>
    /// <returns></returns>
    [HttpGet]
    [Route("{ipAddress}")]
    [ProducesResponseType(typeof(SampleResponse), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(string), StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> GetSecurityDataAsync([FromRoute] string param1, [FromQuery] string param2)
    {
        try
        {
            //Custom logic
        }
        catch (Exception)
        {

            throw;
        }
    }
}
 

Примечание. Убедитесь, что путь XmlDocumentFilepath в разделе «Вывод» вкладки «Сборка» в свойствах проекта установлен.
Свойства проекта