WebAPI入门学习2

上一节，我们说了一下如何创建WebAPI。这一节，我们继续。

之前我们创建了GET，POST，DELETE，PUT四个方法。我们仔细看一下，就发现四个方法的路径都是一样的。.

WebAPI入门学习2

这样的显示方式其实对于一个接口的使用者来说是不够友好的，很多时候很可能不知道这个GET方法是做什么的。那么我们就来细化一下说明。

我们的路由只设定了controller

[ApiController][Route("[controller]")]

我们没使用action。controller我们知道是控制器，这个action，我也不知道怎么说明，就当是某种“行为”/“方法”吧。

我们添加一下action，启动，这时候发生了异常

[Route("[controller]/[action]")]

WebAPI入门学习2

异常原因，是这个，Name = "GetWeatherForecast"因为GET，POST等使用一样，这样是不允许的。

[HttpPost(Name = "GetWeatherForecast")]        public void Post()        {
        }        [HttpDelete(Name = "GetWeatherForecast")]        public void Delete()        {
        }        [HttpPut(Name = "GetWeatherForecast")]        public void Put()        {
        }

我们可以暂时先删除，或者改成不一样的。

[HttpPost(Name = "GetWeatherForecast1")]        public void Post()        {
        }        [HttpDelete(Name = "GetWeatherForecast2")]        public void Delete()        {
        }        [HttpPut(Name = "GetWeatherForecast3")]        public void Put()        {
        }

这样路由就显示不一样了，多了方法名，也就是action。

WebAPI入门学习2

方法名使用的好的化，我们就能大致猜到这个接口的具体功能。

[HttpPost(Name = "GetWeatherForecast1")]        public void PostTxtImformation()        {
        }

WebAPI入门学习2

但是这样也不够，我们可以使用文字说明。

平时写代码的时候，我们可以添加备注/说明。

/// <summary>        /// 文本信息上传接口        /// </summary>        [HttpPost(Name = "GetWeatherForecast1")]        public void PostTxtImformation()        {
        }

如果能够直接把这个显示在swagger里面，岂不是很方便。那么我们就来完成这个效果。

首先我们点击项目属性=》生成，勾选生成API文档。我是用的VS2022，2019等之前的vs版本略有差异。

WebAPI入门学习2

这样生成之后，我们就可以在输出目录，找到一个同名的xml文件，里面是详细的文档说明。

WebAPI入门学习2

文本有了，下面就是要引用它了。

我们大考program.cs，找到这个，开始修改。

builder.Services.AddSwaggerGen();

=》

builder.Services.AddSwaggerGen( g =>            {                var xmlPath = Path.Combine(AppContext.BaseDirectory, "WebApplicationDemo.xml");                g.IncludeXmlComments(xmlPath);            }            );

启动，这样是不是清楚多了。

WebAPI入门学习2

我们可以把所有的方法都加上说明。

/// <summary>        /// 查询天气接口        /// </summary>        /// <returns></returns>        [HttpGet(Name = "GetWeatherForecast")]        public IEnumerable<WeatherForecast> Get()        {            return Enumerable.Range(1, 5).Select(index => new WeatherForecast            {                Date = DateTime.Now.AddDays(index),                TemperatureC = Random.Shared.Next(-20, 55),                Summary = Summaries[Random.Shared.Next(Summaries.Length)]            })            .ToArray();        }        /// <summary>        /// 文本信息上传接口        /// </summary>        [HttpPost(Name = "GetWeatherForecast1")]        public void PostTxtImformation()        {
        }        /// <summary>        /// 文本文件删除接口        /// </summary>        [HttpDelete(Name = "GetWeatherForecast2")]        public void Delete()        {
        }        /// <summary>        /// 信息推送接口        /// </summary>        [HttpPut(Name = "GetWeatherForecast3")]        public void Put()        {
        }

WebAPI入门学习2

这一节就到这里了。

董川民