netcore webapi帮助文档设置

如何建 .netcore webapi 项目这个就不说了，这个都没有没必要看下去。

netcore 2.2 

官方教程

1.Nuget Packages安装，使用程序包管理器控制台，安装命令：Install-Package Swashbuckle.AspNetCore -Pre

或者搜索安装  Swashbuckle.AspNetCore.Swagger

2.生成项目xml文档，多项目的情况下

3.配置Startup.cs。为了直观，我把整个类贴这里了，具体功能看代码注释，自己取舍。

using System;
using System.Net.Http;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using Swashbuckle.AspNetCore.Swagger;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;
using Microsoft.Extensions.PlatformAbstractions;
using System.IO;

namespace CVOL.Api.Test
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            //services.AddDbContext<TodoContext>(opt => opt.UseInMemoryDatabase("TodoList"));
            services.AddMvc().AddJsonOptions(options =>
            {
                //忽略循环引用
                options.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore;
                //不使用驼峰样式的key
                options.SerializerSettings.ContractResolver = new DefaultContractResolver();
                //设置时间格式
                options.SerializerSettings.DateFormatString = "yyyy-MM-dd HH:mm:ss.fff";
            });

            // Register the Swagger generator, defining one or more Swagger documents。info的参数不是必填的。那个版本号尽量不要改，可能会出错
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Title = "我的测试接口",
                    Version = "测试版本1.0",
                    Description = "这是个简单测试接口 ASP.NET Core Web API",
                    TermsOfService = "哈哈哈",
                    Contact = new Contact { Name = "清风神剑", Email = "xx@qq.com", Url = "" }
                });
                var basePath = AppContext.BaseDirectory;
                //Set the comments path for the swagger json and ui.只有一个的话不需要这种循环的方式  
                string[] arr = new string[] { "CVOL.API.Test.xml", "CVOL.Core.Model.xml" };
                foreach (var item in arr)
                {
                    var xmlPath = Path.Combine(basePath, item);
                    options.IncludeXmlComments(xmlPath);
                }


            });


        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            app.UseSwagger();

            // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("v1/swagger.json", "测试接口 V1");
            });
            app.UseMvcWithDefaultRoute();
        }
    }
}

4.设置默认启动项目，不设置的话要打开http://localhost:port/swagger/

5.写个测试代码吧。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using CVOL.Api.Test.Models;
using CVOL.Core.Model;

namespace CVOL.Api.Test.Controllers
{
    /// <summary>
    /// 测试控制器
    /// </summary>
    [Route("api/[controller]")]
    public class TestController : Controller
    {
        /// <summary>
        /// 获得字符串
        /// </summary>
        /// <param name="str">写入的字符串</param>
        /// <returns>获得字符串</returns>
        [HttpGet]
        public string GetStr(string str)
        {
            return "这是获得的字符串：" + str;
        }
        /// <summary>
        /// 获取时间
        /// </summary>
        /// <returns>返回时间</returns>
        [HttpGet]
        [Route("GetDates")]
        public DateTime GetDates()
        {
            return DateTime.Now;
        }
        /// <summary>
        /// 获取类
        /// </summary>
        /// <param name="name">输入名字</param>
        /// <returns>返回类</returns>
        [HttpGet]
        [Route("GetTry")]
        public TodoItem GetTry(string name)
        {
            return new TodoItem { IsComplete = false, Name = name };
        }
        /// <summary>
        /// 插入
        /// </summary>
        /// <param name="item">类</param>
        /// <returns></returns>
        [HttpPost]
        [Route("InsetNew")]
        public TodoItem InsetNew(TodoItem item)
        {
            return item;
        }

        /// <summary>
        /// 获取
        /// </summary>
        /// <param name="nt">类</param>
        /// <returns>返回</returns>
        [HttpPost]
        [Route("GetNew")]
        public NewTestClass GetNew(NewTestClass nt)
        {
            return nt;
        }
    }
}

 上面每个方法的2个标签必填，否则swagger打不开。

最后来看看效果。

样子还是不错的。另外推荐一款测试工具 SOAPUI，挺好用的。