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，挺好用的。