.Net Core3.0 WebApi 项目框架搭建 二:API 文档神器 Swagger

 

 .Net Core3.0 WebApi 项目框架搭建：目录

为什么使用Swagger

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。 

前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

没有API文档工具之前，大家都是手写API文档的，在什么地方书写的都有，有在confluence上写的，有在对应的项目目录下readme.md上写的，每个公司都有每个公司的玩法，无所谓好坏。

书写API文档的工具有很多，但是能称之为“框架”的，估计也只有swagger了。

添加Swagger包

Nuget搜索Swashbuckle.AspNetCore

注册Swagger服务

打开Startup.cs类，编辑 ConfigureServices 类

 public void ConfigureServices(IServiceCollection services)
        {
            var ApiName = "Webapi.Core";

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    // {ApiName} 定义成全局变量，方便修改
                    Version = "V1",
                    Title = $"{ApiName} 接口文档——Netcore 3.0",
                    Description = $"{ApiName} HTTP API V1",

                });
                c.OrderActionsBy(o => o.RelativePath);
            }
                services.AddControllers();
        }

wait，wait，wait，what？光一个注册Swagger就这么多代码？如果我再注册其他的服务，岂不是让ConfigureServices有N行代码。。。。。。，虽然我们可以使用把代码放在#region和#endregion里，但是如果可以将每个服务的配置,都封装到一个方法里面，岂不美哉。如果我需要修改服务的配置代码，只需要到对应的方法里面去修改，而不是去ConfigureServices这个方法里面找到需要修改的服务再去修改，而ConfigureServices里只需要services.addxxx()就行了，代码简约美观直视。

 

原来还真有办法，新建SetUp文件夹，存放要注册的服务，我们新建一个静态类SwaggerSetUp.cs,新建静态方法AddSwaggerSetup，用来注册Swagger

using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace Webapi.Core.SetUp
{
    public static class SwaggerSetUp
    {
        public static void AddSwaggerSetup(this IServiceCollection services)
        {
            if (services == null) throw new ArgumentNullException(nameof(services));

            var ApiName = "Webapi.Core";

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    // {ApiName} 定义成全局变量，方便修改
                    Version = "V1",
                    Title = $"{ApiName} 接口文档——Netcore 3.0",
                    Description = $"{ApiName} HTTP API V1",

                });
                c.OrderActionsBy(o => o.RelativePath);
            });

            }
    }
}

而我们的ConfigureServices只需要一句代码就行了，是不是直观了很多。

启动Swagger

编辑Configure方法

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint($"/swagger/V1/swagger.json", "WebApi.Core V1");

                //路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件,注意localhost:8001/swagger是访问不到的，去launchSettings.json把launchUrl去掉，如果你想换一个路径，直接写名字即可，比如直接写c.RoutePrefix = "doc";
                c.RoutePrefix = "";
            });
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllerRoute(
                        name: "default",
                        pattern: "{controller=Home}/{action=Index}/{id?}");
            });
        }

在 launchSettings.json 文件中的 launchUrl设置为空，或者删掉。

 F5启动项目,直接访问项目根目录，当当当出来了：

 what!  No operations defined in spec!,

问题原因：我们将路由配置统一从Controller中去掉然后endpoints.MapControllerRoute设置了路由模版，由于Swagger无法在Controller中找到[Route("api/[controller]/[action]")]和[ApiController]从而触发了“No operations defined in spec!”的问题

解决方法:将Startup.cs中Configure里的路由模版注释掉，改成endpoints.MapControllers();，增加BaseController.cs并继承ControllerBase，然后在BaseController设置路由模版，让Controller继承BaseController

namespace Webapi.Core.Controllers
{
    /// <summary>
    /// 自定义路由模版
    /// 用于解决swagger文档No operations defined in spec!问题
    /// </summary>
    [Route("api/[controller]/[action]")]
    [ApiController]
    public class BaseController : ControllerBase
    {
    }
}

UserController只需要继承BaseController就行了

 F5运行项目，能够显示了

在上边的截图中，我们可以看到，已经生成了一个 api 列表，我们不仅可以清晰的看到项目中含有那些接口，还可以直接点击发送请求，类似 postman 那样，做接口调试，

但是现在有两个问题：

1、这个接口文档现在还不多，如果多了的话，每个接口对应的意义可能会混淆，

2、另外，这个接口文档，也是方便前端工程师查看的，目前这个这个样式，看起来是挺费解的。

添加接口注释

右键项目名称=>属性=>生成，勾选“输出”下面的“xml文档文件”，这里我用的是相对路径。

 现在呢，配置好了xml文件，接下来需要让系统启动的时候，去读取这个文件了，重新编辑SwaggerSetUp.cs，修改AddSwaggerSetup函数，注意配置的参数 true：

 services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    // {ApiName} 定义成全局变量，方便修改
                    Version = "V1",
                    Title = $"{ApiName} 接口文档——Netcore 3.0",
                    Description = $"{ApiName} HTTP API V1",

                });
                c.OrderActionsBy(o => o.RelativePath);

                // 获取xml注释文件的目录
                var xmlPath = Path.Combine(AppContext.BaseDirectory, "Webapi.Core.xml");
                c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改
            });

给我们的控制器都加上注释，F5运行项目，发现页面注释都加上了

添加Model注释

 新建一个.net core 类库WebApi.Core.Model

新建实体类User

  /// <summary>
    /// 用户表
    /// </summary>
    public class User
    {
        /// <summary>
        /// id
        /// </summary>
        public int Id { get; set; }
        /// <summary>
        /// 姓名
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 年龄
        /// </summary>
        public int Age { get; set; }
    }

右键项目属性，生成 XML 

 编辑SwaggerSetUp.cs，修改AddSwaggerSetup函数，添加以下代码

                var xmlModelPath = Path.Combine(AppContext.BaseDirectory, "Webapi.Core.Model.xml");//这个就是Model层的xml文件名
                c.IncludeXmlComments(xmlModelPath);

UserController新建一个Action

        /// <summary>
        /// 获取User实体
        /// </summary>
        /// <param name="user"></param>
        /// <returns></returns>
        [HttpPost]
        public IActionResult User(User user)
        {
            return Ok(user);
        }

F5运行项目，发现实体类也有了注释

去掉警告

可以发现项目里多了很多警告，要我们添加注释

如果有的小伙伴，不想添加注释，而又不想看到这个强迫症的警告提示，那就可以这么做，

右键项目 属性 -》 Errors and warnings 配置 1591：

隐藏接口

如果不想显示某些接口，直接在controller 上，或者action 上，增加特性

[ApiExplorerSettings(IgnoreApi = true)]