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

asp.net core 一个中小型项目实战的起手式——Swagger配置

程序员文章站 2023-11-06 10:26:46
一、Swagger是什么 Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。 二、如何在项目中加入Swagger Swagger安装引用 右键Web项目依赖项>管理NuGet程序包>在搜索框输入"Swashbuckle.AspNetCore ......

一、swagger是什么

swagger 是一款restful接口的、基于yaml、json语言的文档在线自动生成、代码自动生成的工具。

 

二、如何在项目中加入swagger

  • swagger安装引用

    右键web项目依赖项>管理nuget程序包>在搜索框输入"swashbuckle.aspnetcore",然后单击安装

      

    asp.net core 一个中小型项目实战的起手式——Swagger配置

  • 添加并配置swagger中间件

    首先在startup类中引入swagger:

        using swashbuckle.aspnetcore.swagger;

    将 swagger 生成器添加到configureservices 方法中的服务集合中:

            //注册swagger生成器,定义一个和多个swagger文档
            services.addswaggergen(p =>
            {
                p.swaggerdoc("v1", new info {title = "数据管理器api文档", version = "v1"});
            });

 

    在configure方法中,启用中间件为生成的json文档和swaggerui提供服务:

            //启用中间件服务生成swagger作为json终结点
            app.useswagger();
            //启用中间件服务对swagger-ui,指定swagger json终结点
            app.useswaggerui(p =>
            {
                p.swaggerendpoint("/swagger/v1/swagger.json", "数据管理器api文档 v1"); 
            });

    启动应用,并跳转到 http://localhost:<port>/swagger/v1/swagger.json 生成的描述终结点的文档显示如下json格式。

asp.net core 一个中小型项目实战的起手式——Swagger配置

asp.net core 一个中小型项目实战的起手式——Swagger配置

    

    可在 /swagger 找到 swagger ui。 通过 swagger ui 浏览 api文档,如下所示。

asp.net core 一个中小型项目实战的起手式——Swagger配置

 

  •  为接口方法提供注释

  首先右键【解决方案资源管理器】中的项目,然后选【属性】

  查看“生成”选项卡的【输出】部分下的【xml 文档文件】框

  启用 xml 注释后会为未记录的公共类型和成员提供调试信息。如果出现很多警告信息  例如,以下消息指示违反警告代码 1591。可以在进制显示警告中加入警告代码,这样不会再在错误列表中显示1591类型的警告了。

asp.net core 一个中小型项目实战的起手式——Swagger配置

在swagger注册服务中增加:

            //注册swagger生成器,定义一个和多个swagger文档
            services.addswaggergen(p =>
            {
                p.swaggerdoc("v1", new info {title = "数据管理器api文档", version = "v1"});

                // 为 swagger json and ui设置xml文档注释路径
                var basepath = path.getdirectoryname(typeof(program).assembly.location);//获取应用程序所在绝对目录
                var xmlpath = path.combine(basepath, "datamanager.web.xml");//此处的文件名要对应到项目属性中生成的xml文件名
                p.includexmlcomments(xmlpath);
            });

 

在控制器目录下新增一个webapi测试控制器,测试下效果

 

    [route("api/[controller]/[action]")]
    [apicontroller]
    public class swaggertestcontroller : controllerbase
    {
        /// <summary>
        /// 这是一个swagger测试接口
        /// </summary>
        /// <returns></returns>
        [httpget]
        public iactionresult test()
        {
            return new jsonresult(new {key = "name", value = "test"});
        }
    }

访问/swagger:

asp.net core 一个中小型项目实战的起手式——Swagger配置

好了,今天的在asp.net core webapi使用swagger生成api说明文档的教程就到这里了。希望能够对大家学习在asp.net core中使用swagger生成api文档有所帮助!