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

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

{
  "0": "未知", 
  "1": "男性", 
  "2": "女性"
}
  • [x] Generate API documentation for ASP.NET Core.
  • [x] JsonOutputFormatter use camel case or not determined by the API (Because it’s API).
  • [x] 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

We are programmers, lives in Hangzhou, Zhejiang, China. The difference with other programmers is We are software architects (or want to be), particularly love . NET Core, but we also embrace all the new stuff. (^<>^)

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

PEOPLE