Swagger使用

详细的使用,可以看老张的博客https://www.cnblogs.com/laozhang-is-phi/p/9495624.html

我之前也写过Swagger的使用,使用的是NSwag开源项目。

本次使用Swashbuckle.AspNetCore

开发环境VS2019+.NET CORE 3.1

记录一下使用过程。

1.在Nuget搜索并安装Swashbuckle.AspNetCore版 本次使用的5.0.0版本

 

 

 

 

 

 2.安装完毕开始配置服务

 
private string apiVersionName = "V1";
public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            #region Swagger
            //注册Swagger服务
            services.AddSwaggerGen(c =>
            {


                //添加文本信息
                c.SwaggerDoc(apiVersionName, new OpenApiInfo()
                {
                    Version = apiVersionName,//版本号
                    Title = apiVersionName + "doc",//标题
                    Description = "框架说明文档",//描述
                    Contact = new OpenApiContact() { Url = new System.Uri("http://www.baidu.com"), Name = "Test", Email = "Swagger.Test@xxx.com" }
                });

            });


            #endregion
        }

3.添加Http中间件

#region Swagger
            //中间件 将Api以Json格式Response 路由结点/swagger/v1/swagger.json
            app.UseSwagger();
            //中间件 将Api以html形式Response
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint($"/swagger/{apiVersionName}/swagger.json", $"{apiVersionName}doc");
                //要在应用的根(http://localhost:<port>/) 处提供 Swagger UI，将 RoutePrefix 属性设置为空字符串
                c.RoutePrefix = "";
                //c.HeadContent = "";配置头部内容
                //c.IndexStream 配置自定义的静态页面文件
            });
            #endregion

到此就完成了基础的配置.并且已经设置Swagger的访问地址为根路径.启动后URL输入 http://localhost:20071/index.html 端口号是我本地默认的。即可访问SwaggerUI.

如果出现以下情况,可能是路由结点不对,一般是V1的V的大小写问题,上文代码已经将版本号改为字段所以不会出现了。

 

4.为接口和控制器添加注释完成文档的生成.

给控制器上添加注释.

给Api接口添加注释

 

 

 

 生成XML文档。在项目属性中=》 生成=》XML文档文件  1591是取消其他没有添加注释Api接口的警告.

 

 

 有了文档和注释后 在服务中继续配置。

                var basePath = ApplicationEnvironment.ApplicationBasePath;
　　　　　　　　　 var xmlPath = Path.Combine(basePath, "demoApi.xml");//这个就是刚刚配置的xml文件名
　　　　　　　　　 c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改

运行查看效果.

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

[ApiExplorerSettings(IgnoreApi =true)]

6.描述响应类型 手动控制返回类型和状态码 增加特性

 [ProducesResponseType(typeof(WeatherForecast),200)] 

XML文档就是API接口文档了，UI界面也可以方便查看接口。另外Swagger还可以测试接口，并接入JWT测试，如此可以不使用Postman请求测试了,方便了许多。

Swagger简单配置使用大概就是这样了。