Aiursoft.DocGenerator 8.0.4

dotnet add package Aiursoft.DocGenerator --version 8.0.4                
NuGet\Install-Package Aiursoft.DocGenerator -Version 8.0.4                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Aiursoft.DocGenerator" Version="8.0.4" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Aiursoft.DocGenerator --version 8.0.4                
#r "nuget: Aiursoft.DocGenerator, 8.0.4"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Aiursoft.DocGenerator as a Cake Addin
#addin nuget:?package=Aiursoft.DocGenerator&version=8.0.4

// Install Aiursoft.DocGenerator as a Cake Tool
#tool nuget:?package=Aiursoft.DocGenerator&version=8.0.4                

ASP.NET Core API Document Generator

MIT licensed Pipeline stat Test Coverage NuGet version (Aiursoft.DocGenerator) ManHours Website

A basic API document generator for ASP.NET Core applications. Open source, offline and free.

<div align=center> <img src="./demo.png"> </div>

Features

  • Generate Markdown
  • Generate Json

Open the example

Supports

  • ASP.NET Core 6.0

How to use

First, install Aiursoft.DocGenerator to your ASP.NET Core project from nuget.org:

dotnet add package Aiursoft.DocGenerator

Simply add this line in your Startup.cs:

using Aiursoft.DocGenerator.Services;

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...
    // your middlewares
    // ...
    
    app.UseAiursoftDocGenerator(); // <- Add this.
}

Start your application and browse:

/doc

It just returns your document in JSON format.

[{
	"ControllerName": "HomeController",
	"ActionName": "Index",
	"AuthRequired": false,
	"IsPost": false,
	"Arguments": [],
	"PossibleResponses": ["{\"code\":0,\"message\":\"success.\"}"]
}]

That's all! Happy coding!

Continue? Try runing the example project! Or continue reading.

Customization and API

Change document output address

app.UseAiursoftDocGenerator(options =>
{
    // Default value is '/doc'. You can change it to other path.
    options.DocAddress = "/my-doc";
});

Change document output format

app.UseAiursoftDocGenerator(options =>
{
    // Default format is JSON. You can change it to markdown.
    options.Format = DocFormat.Markdown;
});

Set global possible responses

app.UseAiursoftDocGenerator(options =>
{
    // Default global possible response is an empty list.
    options.GlobalPossibleResponse.Add(new { code = 0, message = "success." });
});

Set possible response for one API

When you can ensure the possible response for one API, add this line to your action:

[Produces(typeof(ResponseModel))] // <- add this in your controller.
public IActionResult HasOutput()
{
    var model = new ResponseModel(); // <- your own class and logic
    return Json(model);
}

Document generation filter

By default, only controllers and actions with [GenerateDoc] attributes will be generated.

To mark a controller or action which generates document, add attribute [GenerateDoc] like this:

using Aiursoft.DocGenerator.Attribute;

[GenerateDoc] // Add this, the entire controller will generate document.
public class HomeController : Controller
{
    [GenerateDoc] // Add this, the action will generate document.
    public IActionResult MyAPI()
    {
        return Json(null);
    }
}

You can change that logic to your own filter:

app.UseAiursoftDocGenerator(options =>
{
    options.IsAPIAction = (action, controller) =>
    {
        // Your own logic. Return bool.
        return action.CustomAttributes.Any(t => t.AttributeType == typeof(GenerateDoc));
    };
}

Authorized action detector

If your API is authorized required, we can detect that in the document. And you can customzie the logic:

using Microsoft.AspNetCore.Authorization;

app.UseAiursoftDocGenerator(options =>
{
    options.JudgeAuthorized = (action, controller) =>
    {
        // Your own logic here. Return bool.
        return
            action.CustomAttributes.Any(t => t.AttributeType == typeof(AuthorizeAttribute)) ||
            controller.CustomAttributes.Any(t => t.AttributeType == typeof(AuthorizeAttribute));
    };
}

How to contribute

There are many ways to contribute to the project: logging bugs, submitting pull requests, reporting issues, and creating suggestions.

Even if you with push rights on the repository, you should create a personal fork and create feature branches there when you need them. This keeps the main repository clean and your workflow cruft out of sight.

We're also interested in your feedback on the future of this project. You can submit a suggestion or feature request through the issue tracker. To make this process more effective, we're asking that these include more information to help define them more clearly.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Aiursoft.DocGenerator:

Package Downloads
Aiursoft.SDK

The base class, tools and extends for Aiursoft web apps.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Aiursoft.DocGenerator:

Repository Stars
AiursoftWeb/Infrastructures
Mirror of: https://gitlab.aiursoft.cn/aiursoft/infrastructures
Version Downloads Last updated
8.0.4 64 12/19/2024
8.0.3 69 12/18/2024
8.0.2 157 10/26/2024
8.0.1 527 2/19/2024
8.0.0 137 2/19/2024
7.0.3 145 2/2/2024
7.0.2 124 1/30/2024
7.0.1 1,137 11/23/2023
7.0.0 1,153 9/5/2023
6.0.26 143 9/5/2023
6.0.25 564 6/26/2023
6.0.24 173 6/26/2023
6.0.22 310 6/18/2023
6.0.21 261 6/14/2023
6.0.20 264 6/5/2023
6.0.19 280 5/27/2023
6.0.18 272 5/27/2023
6.0.17 286 5/27/2023
6.0.16 276 5/27/2023
6.0.15 277 5/27/2023
6.0.14 270 5/27/2023
6.0.13 265 5/19/2023
6.0.12 259 5/19/2023
6.0.11 259 5/19/2023
6.0.10 254 5/19/2023
6.0.9 265 5/19/2023
6.0.8 272 5/11/2023
6.0.7 2,348 8/4/2022
6.0.6 882 7/6/2022
6.0.5 1,134 5/13/2022
6.0.0 978 3/27/2022
5.0.9 972 5/31/2021
5.0.8 861 5/23/2021
5.0.7 853 5/7/2021
5.0.6 853 4/14/2021
5.0.5 934 2/16/2021
5.0.4 867 1/29/2021
5.0.3 872 1/27/2021
5.0.2 960 12/9/2020
5.0.1 870 11/30/2020
5.0.0 785 11/14/2020
3.2.11 1,037 10/18/2020
3.2.10 980 10/3/2020
3.2.9 910 10/2/2020
3.2.8 979 9/10/2020
3.2.7 959 9/2/2020
3.2.6 1,030 8/12/2020
3.2.5 1,027 7/31/2020
3.2.4 993 7/3/2020
3.2.3 950 6/25/2020
3.2.2 970 6/18/2020
3.2.1 971 6/5/2020
3.2.0 1,009 6/4/2020
3.1.14 1,194 6/4/2020
3.1.13 1,109 5/25/2020
3.1.12 1,101 5/20/2020
3.1.11 1,066 5/18/2020
3.1.10 1,070 5/18/2020
3.1.9 1,072 5/17/2020
3.1.8 1,071 5/12/2020
3.1.7 1,132 5/2/2020
3.1.6 1,125 5/1/2020
3.1.5 1,104 4/21/2020
3.1.4 845 4/19/2020
3.1.3 1,632 4/15/2020
3.1.2.2 1,811 4/6/2020
3.1.2.1 1,696 3/19/2020
3.1.2 1,737 2/21/2020
3.1.1.8 1,379 2/17/2020
3.1.1.7 1,350 2/14/2020
3.1.1.6 1,152 1/28/2020
3.1.1.5 1,430 1/22/2020
3.1.1.4 1,140 1/21/2020
3.1.1.2 1,149 1/20/2020
3.1.1 893 1/17/2020