There are many API document generate tools, like swagger, but when ASP.NET Core release v1.0, the swagger hard to use, so love.net team develop a API documentation toolchain for ASP.NET Core. This toolchain provides three different UI, the UI will more details in following section.

Love.Net.Help

An API documentation toolchain for ASP.NET Core.

Join the chat at https://gitter.im/lovedotnet/Love.Net.Help

Features

  • Read XML comments at run time (so the deployment need to include yourAssembly.xml file).
  • Get Enum raw constant value and XML comments.
public enum Gender {
    /// <summary>
    /// 未知.
    /// </summary>
    Unknown,
    /// <summary>
    /// 男性.
    /// </summary>
    Male,
    /// <summary>
    /// 女性.
    /// </summary>
    Female,
}

{
  "0": "未知", 
  "1": "男性", 
  "2": "女性"
}
  • Generate API documentation for ASP.NET Core.
  • JsonOutputFormatter use camel case or not determined by the API (Because it’s API).
  • More…

Packages

How to use

Install Love.Net.Help core package.

PM> Install-Package Love.Net.Help

Configure Services to use Love.Net.Help core library.

Add API help to services services.AddMvcCore().AddApiHelp()

public void ConfigureServices(IServiceCollection services) {
    services.AddMvcCore()
        .AddJsonFormatters(options => {
            options.ContractResolver = new DefaultContractResolver();
        }).AddApiHelp();

    services.UseDefaultAccountService<User>(null);
}

Use UI middleware app.UseApiHelpUI();

PM> Install-Package Love.Net.Help.JsonH

or

PM> Install-Package Love.Net.Help.JsonEditor

or

PM> Install-Package Love.Net.Help.UI

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory) {
    loggerFactory.AddConsole(Configuration.GetSection("Logging"));
    loggerFactory.AddDebug();

    app.UseApiHelpUI();

    app.UseMvc();
}

Browser http://localhost:10571/api/help/ui

Options for API help

public void ConfigureServices(IServiceCollection services) {
    services.AddMvcCore()
        .AddJsonFormatters(options => {
            options.ContractResolver = new DefaultContractResolver();
        }).AddApiHelp(options => {
            options.IgnoreObsoleteApi = true;
            options.LoadingPolicy = LoadingPolicy.Eager;
        });
}

namespace Love.Net.Help {
    public class ApiHelpOptions {
        /// <summary>
        /// Gets or sets a value indicating whether include supported media type.
        /// </summary>
        /// <value><c>true</c> if include supported media type; otherwise, <c>false</c>.</value>
        public bool IncludeSupportedMediaType { get; set; }
        /// <summary>
        /// Gets or sets the value indicating whether ignore obsolete API or not.
        /// </summary>
        /// <value>The value indicating whether ignore obsolete API or not.</value>
        public bool IgnoreObsoleteApi { get; set; } = true;

        /// <summary>
        /// Gets or sets the API document loading policy.
        /// </summary>
        /// <value>The API document loading policy.</value>
        public LoadingPolicy LoadingPolicy { get; set; }
    }

    public enum LoadingPolicy {
        /// <summary>
        /// Indicating eager loading.
        /// </summary>
        Eager,
        /// <summary>
        /// Indicating lazy loading.
        /// </summary>
        Lazy,
    }
}

Loading specified API help

http://localhost:10571/api/help/get?RelativePath=api/Values/{id}&HttpMethod=GET

Overview

Love.Net.Help.JsonH Overview

Love.Net.Help.JsonEditor Overview

Love.Net.Help.UI Overview

ABOUT

I'm a developer, I use C/C++, Java, C# and Swift, but I also embrace all the new stuff.

I'm working at Tencent. My family live in Hangzhou, Zhejiang, China. Maybe the difference with other programmers is I already married, and have a lovely daughter. (^<>^)

A man like me, is unique in the world of existence, no matter where you go, there belonging to my stage. Like desert gold, light can not hide forever! Especially my messy hair, melancholy eyes, sigh of stubble, handsome face, are deeply addicted whom even I.

ELSEWHERE