.NetCore中使用Swagger文档自动生成API接口及注释

 

1、创建一个.NetCore WebApi项目

 

2、使用Nuget安装Swagger，安装的命令是:

Install-Package Swashbuckle.AspNetCore -Pre

 

3、安装完Swagger插件之后，在Startup.cs文件中的ConfigureServices方法和Configure方法注册并使用Swagger服务。

在ConfigureServices方法中添加如下代码：

public void ConfigureServices(IServiceCollection services)
        {
            //注册Swagger
            services.AddSwaggerGen(c =>
            {
                //V1：后端版本
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Title = "Gs.Swagger", //项目名称 
                    Version = "v1"  //版本 和后端版本没有关系
                });
            });

            services.AddControllers();
        }

 

在Configure方法中添加如下代码：

//注册好之后，接下来引用Swagger服务
app.UseSwagger();
app.UseSwaggerUI(c => //UI界面
{
    //参数1：写上动态生成的json信息；其中的版本和上面SwaggerDoc中的版本一致
    //参数2：文档名称
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Gs.Swagger");
});

4、到目前为止，项目中已经安装好了Swagger，最后更改Properties下的launchSettings.json，设置Swagger文档为起始页

5、运行项目，就可以看到项目的接口文档了

6、配置swagger注释

项目属性→生成→勾选“XML文档文件”

7、在Startup文件中AddSwaggerGen中添加

                //将application层中的注释添加到SwaggerUI中，这样就会有中文提示，比较友好
                var baseDirectory = AppDomain.CurrentDomain.BaseDirectory;
                var xmlPath = "RFIDExtend.xml";//你自己的Application项目
                var commentsFile = Path.Combine(baseDirectory, xmlPath);
                //将注释的XML文档添加到SwaggerUI中
                c.IncludeXmlComments(commentsFile);

文中项目GitHub地址：https://github.com/wangongshen/GsSwagger