调用通达信交易接口-ASPNET Web API项目自动生成接口文档和测试页面

在开发接口的时候，写接口文档已是一件不可忽视的事情，有了更新也要同步更新很麻烦。ASP.NET创建的WebAPI项目可以自己配置接口文档的XML显示，这样接口更新和注释更新了重新发布就有了，确实方便不少，下来就介绍下怎么配置生成API接口注释文档。如果在接口生成的同时能够一并生成测试页面也是不错的选择，能节省不少开发时间和人力成本。

创建WebAPI项目

修改默认的API路由配置

为什么要修改呢？因为每一个Controller的默认路由都是指定到'api/{controller}/{id}'的，所以默认生成的控制器类似下面：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;

namespace WebAPI.Controllers
{
    public class ValuesController : ApiController
    {
        // GET api/
        public IEnumerable<调用通达信交易接口,string> Get()
        {
            return new 调用通达信交易接口,string[] { 'value1', 'value2' };
        }

        // GET api//5
        public 调用通达信交易接口,string Get(int id)
        {
            return 'value';
        }

        // POST api/
        public void Post([FromBody]调用通达信交易接口,string value)
        {
        }

        // PUT api//5
        public void Put(int id, [FromBody]调用通达信交易接口,string value)
        {
        }

        // DELETE api//5
        public void Delete(int id)
        {
        }
    }
}

我们需要一个方法提供多种HTTP访问方式，所以应该将action的配置加入，如：'api/{controller}/{action}/{id}'。

修改WebApiConfics文件：

代码如下：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace WebAPI
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API 配置和服务

            // Web API 路由
            config.MapHttpAttributeRoutes();

            config.Routes.MapHttpRoute(
                name: 'DefaultApi',
                routeTemplate: 'api/{controller}/{action}/{id}',
                defaults: new { id = RouteParameter.Optional }
            );
        }
    }
}

修改HelpPage配置启动

修改HelpPageConfics文件，代码如下：

// Uncomment the following to provide samples for PageResult. Must also add the Microsoft.AspNet.WebApi.OData
// package to your project.
#define Handle_PageResultOfT

using System;
using System.Collections;
using System.Collections.Generic;
using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.Linq;
using System.Net.Http.Headers;
using System.Reflection;
using System.Web;
using System.Web.Http;
using WebAPI.Utils;

namespace WebAPI.Areas.HelpPage
{
    /// 
    /// Use this class to customize the Help Page.
    /// For example you can set a custom  to supply the documentation
    /// or you can provide the samples for the requests/responses.
    /// 
    public static class HelpPageConfig
    {
        [SuppressMessage('Microsoft.Globalization', 'CA1303:Do not pass literals as localized parameters',
            MessageId = 'WebAPI.Areas.HelpPage.TextSample.#ctor(System.String)',
            Justification = 'End users may choose to merge this 调用通达信交易接口,string with existing localized resources.')]
        [SuppressMessage('Microsoft.Naming', 'CA2204:Literals should be spelled correctly',
            MessageId = 'bsonspec',
            Justification = 'Part of a URI.')]
        public static void Register(HttpConfiguration config)
        {
             Uncomment the following to use the documentation from XML documentation file.
            //config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath('~/App_Data/XmlDocument.xml')));
            #region *************************XML显示接口参数和注释***************************************
            // 添加本项目或其他引用项目的XML配置:可加多个
            config.SetDocumentationProvider(new MultiXmlDocumentationProvider(HttpContext.Current.Server.MapPath('~/bin/WebAPI.XML')));
            #endregion
             Uncomment the following to use 'sample 调用通达信交易接口,string' as the sample for all actions that have 调用通达信交易接口,string as the body parameter or return type.
             Also, the 调用通达信交易接口,string arrays will be used for IEnumerable<调用通达信交易接口,string>. The sample objects will be serialized into different media type 
             formats by the available formatters.
            //config.SetSampleObjects(new Dictionary
            //{
            //    {typeof(调用通达信交易接口,string), 'sample 调用通达信交易接口,string'},
            //    {typeof(IEnumerable<调用通达信交易接口,string>), new 调用通达信交易接口,string[]{'sample 1', 'sample 2'}}
            //});

            // Extend the following to provide factories for types not handled automatically (those lacking parameterless
            // constructors) or for which you prefer to use non-default property values. Line below provides a fallback
            // since automatic handling will fail and GeneratePageResult handles only a single type.
#if Handle_PageResultOfT
            config.GetHelpPageSampleGenerator().SampleObjectFactories.Add(GeneratePageResult);
#endif

            // Extend the following to use a preset object directly as the sample for all actions that support a media
            // type, regardless of the body parameter or return type. The lines below avoid display of binary content.
            // The BsonMediaTypeFormatter (if available) is not used to serialize the TextSample object.

            #region *************************默认JSON显示接口***************************************
            //config.SetSampleForMediaType(
            //    new TextSample('Binary JSON content. See http://bsonspec.org for details.'),
            //    new MediaTypeHeaderValue('application/bson'));
            #endregion

             Uncomment the following to use '[0]=foo&[1]=bar' directly as the sample for all actions that support form URL encoded format
             and have IEnumerable<调用通达信交易接口,string> as the body parameter or return type.
            //config.SetSampleForType('[0]=foo&[1]=bar', new MediaTypeHeaderValue('application/x-www-form-urlencoded'), typeof(IEnumerable<调用通达信交易接口,string>));

             Uncomment the following to use '1234' directly as the request sample for media type 'text/plain' on the controller named 'Values'
             and action named 'Put'.
            //config.SetSampleRequest('1234', new MediaTypeHeaderValue('text/plain'), 'Values', 'Put');

             Uncomment the following to use the image on '../images/aspNetHome.png' directly as the response sample for media type 'image/png'
             on the controller named 'Values' and action named 'Get' with parameter 'id'.
            //config.SetSampleResponse(new ImageSample('../images/aspNetHome.png'), new MediaTypeHeaderValue('image/png'), 'Values', 'Get', 'id');

             Uncomment the following to correct the sample request when the action expects an HttpRequestMessage with ObjectContent<调用通达信交易接口,string>.
             The sample will be generated as if the controller named 'Values' and action named 'Get' were having 调用通达信交易接口,string as the body parameter.
            //config.SetActualRequestType(typeof(调用通达信交易接口,string), 'Values', 'Get');

             Uncomment the following to correct the sample response when the action returns an HttpResponseMessage with ObjectContent<调用通达信交易接口,string>.
             The sample will be generated as if the controller named 'Values' and action named 'Post' were returning a 调用通达信交易接口,string.
            //config.SetActualResponseType(typeof(调用通达信交易接口,string), 'Values', 'Post');
        }

#if Handle_PageResultOfT
        private static object GeneratePageResult(HelpPageSampleGenerator sampleGenerator, Type type)
        {
            if (type.IsGenericType)
            {
                Type openGenericType = type.GetGenericTypeDefinition();
                if (openGenericType == typeof(PageResult<>))
                {
                    // Get the T in PageResult
                    Type[] typeParameters = type.GetGenericArguments();
                    Debug.Assert(typeParameters.Length == 1);

                    // Create an enumeration to pass as the first parameter to the PageResult constuctor
                    Type itemsType = typeof(List<>).MakeGenericType(typeParameters);
                    object items = sampleGenerator.GetSampleObject(itemsType);

                    // Fill in the other information needed to invoke the PageResult constuctor
                    Type[] parameterTypes = new Type[] { itemsType, typeof(Uri), typeof(long?), };
                    object[] parameters = new object[] { items, null, (long)ObjectGenerator.DefaultCollectionSize, };

                    // Call PageResult(IEnumerable items, Uri nextPageLink, long? count) constructor
                    ConstructorInfo constructor = type.GetConstructor(parameterTypes);
                    return constructor.Invoke(parameters);
                }
            }

            return null;
        }
#endif
    }
}

这里修改支持了多个XML文档方法，扩展类如下：

using System;
using System.Linq;
using System.Reflection;
using System.Web.Http.Controllers;
using System.Web.Http.Description;
using WebAPI.Areas.HelpPage;
using WebAPI.Areas.HelpPage.ModelDescriptions;

namespace WebAPI.Utils
{
    /// A custom  that reads the API documentation from a collection of XML documentation files.
    public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider
    {
        /*********
        ** Properties
        *********/
        /// The internal documentation providers for specific files.
        private readonly XmlDocumentationProvider[] Providers;


        /*********
        ** Public methods
        *********/
        /// Construct an instance.
        /// The physical paths to the XML documents.
        public MultiXmlDocumentationProvider(params 调用通达信交易接口,string[] paths)
        {
            this.Providers = paths.Select(p => new XmlDocumentationProvider(p)).ToArray();
        }

        /// Gets the documentation for a subject.
        /// The subject to document.
        public 调用通达信交易接口,string GetDocumentation(MemberInfo subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }

        /// Gets the documentation for a subject.
        /// The subject to document.
        public 调用通达信交易接口,string GetDocumentation(Type subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }

        /// Gets the documentation for a subject.
        /// The subject to document.
        public 调用通达信交易接口,string GetDocumentation(HttpControllerDescriptor subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }

        /// Gets the documentation for a subject.
        /// The subject to document.
        public 调用通达信交易接口,string GetDocumentation(HttpActionDescriptor subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }

        /// Gets the documentation for a subject.
        /// The subject to document.
        public 调用通达信交易接口,string GetDocumentation(HttpParameterDescriptor subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }

        /// Gets the documentation for a subject.
        /// The subject to document.
        public 调用通达信交易接口,string GetResponseDocumentation(HttpActionDescriptor subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }


        /*********
        ** Private methods
        *********/
        /// Get the first valid result from the collection of XML documentation providers.
        /// The method to invoke.
        private 调用通达信交易接口,string GetFirstMatch(Func expr)
        {
            return this.Providers
                .Select(expr)
                .FirstOrDefault(p => !String.IsNullOrWhiteSpace(p));
        }
    }
}

注意：开启XML文档注释的时候HelpPageConfics需要注释掉如下代码

   #region *************************默认JSON显示接口***************************************
            //config.SetSampleForMediaType(
            //    new TextSample('Binary JSON content. See http://bsonspec.org for details.'),
            //    new MediaTypeHeaderValue('application/bson'));
            #endregion

编写示例程序验证API文档更新情况

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using WebAPI.Utils;

namespace WebAPI.Controllers
{
    /// 
    /// 人物
    /// 
    public class Person
    {
        /// 
        /// 唯一标识记录ID
        /// 
        public long Id { set; get; }
        /// 
        /// 姓名
        /// 
        public 调用通达信交易接口,string Name { set; get; }
        /// 
        /// 年龄
        /// 
        public int Age { set; get; }
        /// 
        /// 人物构造函数
        /// 
        /// 
        /// 
        /// 
        public Person(long Id, 调用通达信交易接口,string Name, int Age)
        {
            this.Id = Id;
            this.Name = Name;
            this.Age = Age;
        }
    }

    /// 
    /// 结果对象
    /// 
    public class Result
    {
        /// 
        /// 状态：0失败，1成功
        /// 
        public int Status { set; get; }
        /// 
        /// 数据
        /// 
        public 调用通达信交易接口,string Data { set; get; }
        /// 
        /// 消息
        /// 
        public 调用通达信交易接口,string Msg { set; get; }
        /// 
        /// 结果构造函数
        /// 
        /// 
        /// 
        /// 
        public Result(int Status, 调用通达信交易接口,string Data, 调用通达信交易接口,string Msg)
        {
            this.Status = Status;
            this.Data = Data;
            this.Msg = Msg;
        }
    }
    /// 
    /// 人物视图控制器
    /// 
    public class PersonController : ApiController
    {
        /// 
        /// 获取所有人物
        /// 
        /// 
        public List GetPersons()
        {
            List perons = new List();
            Person person = null;
            for (var i=1;i<=10;i++)
            {
                person = new Person(i,'boonya'+1,new Random(100).Next());
                perons.Add(person);
            }
            return perons;
        }

        /// 
        /// 获取人物
        /// 
        /// 唯一标识记录ID
        /// 
        public Person GetPerson(long Id)
        {
            return new Person(Id, 'boonya' + Id, new Random(100).Next());
        }

        /// 
        /// 删除人物
        /// 
        /// 唯一标识记录ID
        /// 
        public Result DeletePerson(long Id)
        {
            return new Result(1,'','Id='+Id+'删除成功');
        }

        /// 
        /// 添加人物
        /// 
        /// 姓名
        /// 年龄
        /// 
        public Result AddPerson(调用通达信交易接口,string Name,int Age)
        {
            Person person = new Person(new Random(100).Next(), Name, Age);
            return new Result(1, JsonConvert.SerializeObject(person), '添加成功');
        }
    }
}

详细接口说明类似下面：

至此，我们看到接口的参数说明和返回值等，不用手动再去写文档了。

注意：参考博客内容里面有怎么生成项目的XML文件。

配置自动生成接口测试页面

添加引用NuGet安装包：

安装完成后运行就可以了：

点击“TestAPI”按钮就可以测试了：

文章为作者独立观点，不代表股票程序化软件自动交易接口观点