asp.net core 3.1/swagger

本文使用特性来描述接口而不是xml文件，使用特性可自定义接口在swaggerUI上的描述

安装nuget包：Swashbuckle.AspNetCore.SwaggerUI和Swashbuckle.AspNetCore.Annotations，配置swagger：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
?
namespace swaggerweb
{
    public class Startup
    {
        private readonly string swaggerDocName = "weather";
?
        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.AddSwaggerGen(opt =>
            {
                opt.SwaggerDoc(swaggerDocName, new OpenApiInfo()
                {
                    Version = "v1",
                    Title = "WeatherForecast",
                    Description = "天气预报"
                });
                // 使用annotation来描述接口，不依赖XML文件
                opt.EnableAnnotations();
?
                // 下面两句，将swagger文档中controller名使用GroupName替换
                // 在Swagger中，一个Tag可以看作是一个API分组
                opt.DocInclusionPredicate((_, apiDescription) => string.IsNullOrWhiteSpace(apiDescription.GroupName) == false);
                opt.SwaggerGeneratorOptions.TagsSelector = (apiDescription) => new[] { apiDescription.GroupName };
            });
            services.AddControllers();
        }
?
        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            app.UseSwagger(opt =>
            {
                // 相对路径加载swagger文档
                //opt.RouteTemplate = "swagger/{documentName}";
            })
            .UseSwaggerUI(opt =>
            {
                opt.SwaggerEndpoint($"{swaggerDocName}/swagger.json", "天气预报API文档");
            });
?
            app.UseRouting();
?
            app.UseAuthorization();
?
            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
                // 也可以在这里配置swagger文档路径
                //endpoints.MapSwagger();
            });
        }
    }
}

Controller和Action上使用特性：ApiExplorerSettings和SwaggerOperation：

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Swashbuckle.AspNetCore.Annotations;
using System;
using System.Collections.Generic;
using System.Linq;
?
namespace swaggerweb.Controllers
{
    [ApiExplorerSettings(GroupName = "天气预报")]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };
?
        private readonly ILogger<WeatherForecastController> _logger;
?
        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }
?
        [HttpGet]
        [SwaggerOperation(Summary = "获取天气预报信息")]
        public IEnumerable<WeatherForecast> Get()
        {
            var rng = new Random();
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = Summaries[rng.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}

效果图：

推荐阅读

Grouping Operations With Tags