在. net core 3.1 WebApi中使用Swagger

编辑于 2020/04/02

Jwt Bearer权限认证+Swagger 第二篇 已经完成了！
在. net core 3.1 WebApi中使用Swagger框架+Jwt权限验证 第二篇

前言

---

编辑API接口文档对任何一个开发人员来说都算是比较重复，又无聊的工作，所以，需要一种快速有效的方法来构建api说明文档并且具备一定的扩展能力。Swagger就具备这些能力，现在Swagger可以说是当下最受欢迎的生成REST APIs风格文档工具。
书写API文档的工具有很多，但是能称之为“框架”的，估计也只有swagger了。

一. 创建工程

---

创建 asp. net core WebAPI 3.1项目，这里就不过多演示了。

二. 安装Nuget包依赖

---

在Nuget包中搜索Swashbuckle.AspNetCore安装

博主当前安装的版本是5.2.1

Nuget包

三. 配置服务

---

Startup.cs 中 ConfigureServices方法

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

    #region Swagger
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v0.1.0",
            Title = "Blog.Core API",
            Description = "API文档",
            TermsOfService = new Uri("https://www.jianshu.com/u/1117a3ecacbc"),
            Contact = new OpenApiContact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = new Uri("https://www.jianshu.com/u/1117a3ecacbc") }
        });
    });
    #endregion
}

Startup.cs 中 Configure方法

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

    #region Swagger
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");

        //直接在根域名访问(localhost:8001/index.html)
        //c.RoutePrefix = "";

    });
    #endregion

    app.UseRouting();

    app.UseAuthorization();

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

三. 运行

---

启动程序后，在Url后面添加Swagger即可访问Swagger

Url

这样，Swagger就搭建完成了，马上F5运行看看！是不是非常简单，运行结果如下。

Swagger

点击方法内的Try it out，再点击Execute，就完成了一次接口调用，是不是非常方便。

四. 接口方法显示注释

---

当接口非常多的时候，那么就需要在接口上显示中文注释，这样也方便前端在调用接口是方便理解。

1. 右键单击WebApi项目--属性--生成--输出

WebApi项目设置

2. 修改Startup.cs 中 ConfigureServices方法

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

    #region Swagger
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v0.1.0",
            Title = "Blog.Core API",
            Description = "API文档",
            TermsOfService = new Uri("https://www.jianshu.com/u/1117a3ecacbc"),
            Contact = new OpenApiContact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = new Uri("https://www.jianshu.com/u/1117a3ecacbc") }
        });

        var basePath = AppContext.BaseDirectory;
        var xmlPath = Path.Combine(basePath, "NetCore.Blogs.Swagger.xml");//这个就是刚刚配置的xml文件名
        c.IncludeXmlComments(xmlPath, true);
    });

    #endregion
}

3. 在Controller的方法中进行注释

注释方法

当然也可以注释Controller

注释控制器

运行查看效果

显示效果

五. 忽略CS1591警告

---

编译后发现一大堆的CS1591警告，虽然不会造成程序的影响，但是强迫症患者看着难受。
忽略警告非常简单，只需要在
WebApi项目--属性--生成下

忽略警告设置

六. 设置swagger页面为首页

---

虽然可以通过输入/swagger进行访问swagger，但是这样还是不是很方便的。

1. 打开WebAPI项目下的launchsettings.json文件

Settings

2. 设置 launchUrl为swagger

launchUrl

再次启动，就会发现直接启定到Swagger页面了，是不是很方便。

七. 源码

---

码云