.net core 使用swagger自动生成接口文档

发布时间：2020-12-16 23:35:22 所属栏目：百科来源：网络整理

导读：?前言 swagger是一个api文档自动生动工具,还集成了在线调试. 可以为项目自动生成接口文档,非常的方便快捷 Swashbuckle.AspNetCore 是一个开源项目，用于生成 ASP.NET Core Web API 的 Swagger 文档. 本文采用这个! ? 一. 利用nuget添加引用?washbuckle.AspNe

?前言

swagger是一个api文档自动生动工具,还集成了在线调试. 可以为项目自动生成接口文档,非常的方便快捷

Swashbuckle.AspNetCore 是一个开源项目，用于生成 ASP.NET Core Web API 的 Swagger 文档. 本文采用这个!

一. 利用nuget添加引用?washbuckle.AspNetCore

二. 在 Startup.cs 里面注册服务,添加中间件

添加引用

      using Swashbuckle.AspNetCore.Swagger;

注册服务

        public void ConfigureServices(IServiceCollection services)
        {
            //注册Swagger生成器，定义一个和多个Swagger 文档
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1",new Info { Title = "My API",Version = "v1" });//设置版本号,标题
                var xmlPath = Path.Combine(Path.GetDirectoryName(typeof(Program).Assembly.Location),"SwaggerApi.xml");// 为 Swagger JSON and UI设置xml文档注释路径
                c.IncludeXmlComments(xmlPath);//只有设置了xmlm文档的路径生成的文档才会有注释
            });

           services.AddMvc();

添加中间件

        public void Configure(IApplicationBuilder app,IHostingEnvironment env)
        {
            //启用中间件服务生成Swagger作为JSON终结点
            app.UseSwagger();
            //启用中间件服务对swagger-ui，指定Swagger JSON终结点
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json","My API V1");
            });
            app.UseMvc();
        }

三. 修改项目属性

1. 在生成的输入里面勾选 XML文档文件,并将文件名更改为注册服务的定义的文件名

2. 可以选择隐藏1591的错误提示,不隐藏所有没有写注释的地方都会有警告,

?四. 写接口调试

1. 创建返回实体,要想接口中自带注释说明,实体必须要写上注释

        /// <summary>
        /// 返回实体
        /// </summary>
        public class TestResult
        {
            /// <summary>
            /// 用户Id
            /// </summary>
            public string Id;
            /// <summary>
            /// 用户名称
            /// </summary>
            public string Name;
        }

2. 写接口

需要注意action的路由,请求方式,返回类型,都要加上,否则会导致文档不全

        /// <summary>
        /// 测试接口
        /// </summary>
        /// <param name="id">用户Id</param>
        /// <returns></returns>
        [Route("api/[controller]/[action]")]
        [HttpGet]
        [ProducesResponseType(typeof(TestResult),200)]
        public IActionResult Test(string id)
        {
            return Ok(new TestResult
            {
                Id = id,Name = "Hello World"
            });
        }

五. 查看结果

https://localhost:xxxx/swagger/index.html

展开

六. 在线调试点击 Try It Out

填写参数

结果

（编辑：李大同）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!