欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

.NetCore WebApi——Swagger简单配置

程序员文章站 2022-06-28 20:19:33
在前后端分离的大环境下,API接口文档成为了前后端交流的一个重点。Swagger让开发人员摆脱了写接口文档的痛苦。 官方网址:https://swagger.io/ 在.Net Core WebApi中通过简单配置即可使用这一强大的功能。 1.新建一个API的项目 选择 API 项目 2.引入Swa ......

在前后端分离的大环境下,api接口文档成为了前后端交流的一个重点。swagger让开发人员摆脱了写接口文档的痛苦。

官方网址:

在.net core webapi中通过简单配置即可使用这一强大的功能。

 

1.新建一个api的项目.NetCore WebApi——Swagger简单配置

选择 api 项目

.NetCore WebApi——Swagger简单配置

 

2.引入swagger包。.net core 中支持两个分别为swashbuckle和nswag。两者的配置大同小异。这里以swashbuckle为例。

方式1:选择工具——nuget包管理——管理解决方案的nuget包

.NetCore WebApi——Swagger简单配置

 

搜索:swashbuckle.aspnetcore  安装即可

 

.NetCore WebApi——Swagger简单配置

 

方式2:直接在程序包管理控制台输入:install-package swashbuckle.aspnetcore  回车即可安装

.NetCore WebApi——Swagger简单配置

 

安装之后在项目的nuget包中就可以看到了

.NetCore WebApi——Swagger简单配置

 

3.配置swagger中间件

   3.1 在startup类configureservices方法中添加swagger服务并配置文档信息

  

 public void configureservices(iservicecollection services)
        {
            // 注册swagger服务
            services.addswaggergen(c =>
            {
                // 添加文档信息
                c.swaggerdoc("v1", new info { title = "corewebapi", version = "v1" });
            });
            services.addmvc().setcompatibilityversion(compatibilityversion.version_2_2);
        }

 

   3.2 在 startup类configure 方法中,启用中间件为生成的 json 文档和 swagger ui 提供服务

  

 public void configure(iapplicationbuilder app, ihostingenvironment env)
        {
            if (env.isdevelopment())
            {
                app.usedeveloperexceptionpage();
            }
            else
            {
                // the default hsts value is 30 days. you may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.usehsts();
            }
      
            app.usehttpsredirection();
            // 启用swagger中间件
            app.useswagger();

            // 配置swaggerui
            app.useswaggerui(c =>
            {
                c.swaggerendpoint("/swagger/v1/swagger.json", "corewebapi");
               
            });
            app.usemvc();
        }

 

 右键项目属性,将url地址固定到某个端口

.NetCore WebApi——Swagger简单配置

 

然后将启动项设置为当前项目,然后启动。

.NetCore WebApi——Swagger简单配置

 

在根目录目前是没有东西的。下一步将在根目录处使用swaggerui

.NetCore WebApi——Swagger简单配置

 

将routeprefix属性设置为空

    app.usehttpsredirection();
            // 启用swagger中间件
            app.useswagger();

            // 配置swaggerui
            app.useswaggerui(c =>
            {
                c.swaggerendpoint("/swagger/v1/swagger.json", "corewebapi");
                c.routeprefix = string.empty;
            });

再次启动项目,swaggerui文档成功显示出来。整体简洁大方。

.NetCore WebApi——Swagger简单配置

 api的信息说明:传递给addswaggergen()的方法可配置一些api的信息说明以及作者信息等,来展示到ui页面。修改addswaggergen()方法。 

// 注册swagger服务
            services.addswaggergen(c =>
            {
                // 添加文档信息
                c.swaggerdoc("v1", new info
                {
                    title = "corewebapi",
                    version = "v1",
                    description="asp.net core webapi",
                    contact=new contact
                    {
                        name="jee",
                        email="xiaomaprincess@gmail.com"
                    }
                });
            });

展示对应的信息

.NetCore WebApi——Swagger简单配置

 4.启用xml注释。上边的效果只有一个简单说明,并没有我们在后台写的注释。启用xml注释之后可以轻松映射到ui界面方便前端开发人员理解。

右键当前项目——编辑****.csproj 的文件  在propertygroup标签组中添加如下两条

<generatedocumentationfile>true</generatedocumentationfile> <nowarn>$(nowarn);1591</nowarn>

这两句的大概意思就是启用xml注释,并忽略未写注释的警告。不添加1591如果某个方法未写 "///"各式的注释,vs会有警示的消息。

 .NetCore WebApi——Swagger简单配置

之后addswaggergen()方法中读取xml文件路径并启用

       // 注册swagger服务
            services.addswaggergen(c =>
            {
                // 添加文档信息
                c.swaggerdoc("v1", new info
                {
                    title = "corewebapi",
                    version = "v1",
                    description="asp.net core webapi",
                    contact=new contact
                    {
                        name="jee",
                        email="xiaomaprincess@gmail.com"
                    }
                });
                // 使用反射获取xml文件。并构造出文件的路径
                var xmlfile = $"{assembly.getexecutingassembly().getname().name}.xml";
                var xmlpath = path.combine(appcontext.basedirectory, xmlfile);
                // 启用xml注释. 该方法第二个参数启用控制器的注释,默认为false.
                c.includexmlcomments(xmlpath,true);
            });

再次启动项目,可以看到写的注释全部都映射出来了

.NetCore WebApi——Swagger简单配置

 

text类的返回值也可以映射出来

.NetCore WebApi——Swagger简单配置

 

models文件夹中的实体也可以映射在接口下方

.NetCore WebApi——Swagger简单配置

 

 总结:   在.net core中配置swagger非常之快速。但这也是堪堪达到可以用的程度,算是入门级别吧。

源码:github

https://github.com/xiaomaprincess/asp.netcore-webapi