Asp.Net Core学习笔记6——Swagger实现API文档功能

Asp.Net Core学习笔记——Swagger实现API文档功能

1.简介

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。它提供了一个Web UI，通过这UI，你不仅可以浏览有关API的信息，而且可以在线测试API。

2.创建ASP.NET Core Web API项目

 

 在ConfigureServices添加Swagger中间件。

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            //注册Swagger生成器，定义一个和多个Swagger 文档
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1.0.0",
                    Title = "我的接口"
                });


            });
        }

选择项目右键属性

 

先引入NuGet包:Microsoft.Extensions.PlatformAbstractions。

如果对接口做了xml注释，要在Startup添加如下代码：

                //如果对接口做了xml注释，要在Startup添加如下代码
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "MySwaggerDemo.xml");
                c.IncludeXmlComments(xmlPath);

　

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            //注册Swagger生成器，定义一个和多个Swagger 文档
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1.0.0",
                    Title = "我的接口"
                });
                //如果对接口做了xml注释，要在Startup添加如下代码
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "MySwaggerDemo.xml");
                c.IncludeXmlComments(xmlPath);
            });
        }

在Configure配置Swagger中间件

　　　　 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            //启用中间件服务生成Swagger作为JSON终结点
            app.UseSwagger();
            //启用中间件服务对swagger-ui，指定Swagger JSON终结点
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            });

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

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

添加一个控制器

    /// <summary>
    /// User控制器
    /// </summary>
    [Route("api/[controller]")]
    [ApiController]
    public class UserController : ControllerBase
    {
        /// <summary>
        /// 根据Id获取信息
        /// </summary>
        /// <param name="id">Id</param>
        /// <returns></returns>
        [HttpPost("GetInfoById")]
        public string GetName(string id = "")
        {
            return "张三";
        }
    }

在launchSettings.json中修改launchUrl数值量，从而改变默认启动页。

运行项目

3.支持多个 Api版本

通过 NuGet 安装此软件包：Microsoft.AspNetCore.Mvc.Versioning。

在Startup.cs类的ConfigureServices()方法中配置服务：
services.AddApiVersioning()；

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddApiVersioning();
}

在Startup.cs类的Configure方法加入app.UseApiVersioning()启用多个API版本。

使用MapToApiVersion定义特定Action API版本号(访问路径：http://localhost:5000/api/[controller]?api-version=1.0)。

    /// <summary>
    /// User控制器
    /// </summary>
    [ApiVersion("1.0")]
    [Route("api/[controller]")]
    [ApiController]
    public class UserController : ControllerBase
    {
        /// <summary>
        /// 根据Id获取信息
        /// </summary>
        /// <param name="id">Id</param>
        /// <returns></returns>
        [MapToApiVersion("1.0")]
        [HttpPost("GetInfoById")]
        public string GetName(string id = "")
        {
            return "张三";
        }
    }

在Startup.cs类的Configure方法中将services.AddApiVersioning()：

services.AddApiVersioning(options => options.AssumeDefaultVersionWhenUnspecified = true);

这样写的目的是让ASP.NET Core 把默认的控制器和Action设置版本1.0。

其实我们也可以改成这样的方式： http://localhost:5000/api/v1/values访问：

    /// <summary>
    /// User控制器
    /// </summary>
    [ApiVersion("1.0")]
    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiController]
    public class UserController : ControllerBase
    {
        /// <summary>
        /// 根据Id获取信息
        /// </summary>
        /// <param name="id">Id</param>
        /// <returns></returns>
        [MapToApiVersion("1.0")]
        [HttpPost("GetInfoById")]
        public string GetName(string id = "")
        {
            return "张三";
        }
    }

服务配置为从特定的媒体类型：

    services.AddApiVersioning(options =>
    {
        options.ApiVersionReader = new MediaTypeApiVersionReader();
        options.AssumeDefaultVersionWhenUnspecified = true;
        options.ApiVersionSelector = new CurrentImplementationApiVersionSelector(options);
    });

发送HTTP请求时，在请求头中content-type指定API版本号，若不指定版本默认使用最新版本：