AttribDoc 1.1.0
There is a newer version of this package available.
See the version list below for details.
See the version list below for details.
dotnet add package AttribDoc --version 1.1.0
NuGet\Install-Package AttribDoc -Version 1.1.0
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="AttribDoc" Version="1.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add AttribDoc --version 1.1.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: AttribDoc, 1.1.0"
#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 AttribDoc as a Cake Addin #addin nuget:?package=AttribDoc&version=1.1.0 // Install AttribDoc as a Cake Tool #tool nuget:?package=AttribDoc&version=1.1.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
AttribDoc
A simple library that allows you to document HTTP APIs via attributes.
Example
[DocSummary("Adds A to B.")]
[DocError(typeof(NotImplementedException), "A number is negative")]
[DocQueryParam("a", "The first number to add.")]
[DocQueryParam("b", "The second number to add.")]
public static int Add(int a, int b)
{
if (a < 0) throw new NotImplementedException();
if (b < 0) throw new NotImplementedException();
return a + b;
}
using System.Reflection;
using System.Text.Json;
using AttribDoc;
using AttribDoc.Example;
Console.WriteLine(ExampleApi.Add(1, 1));
ExampleDocumentationGenerator generator = new();
Documentation documentation = generator.Document(Assembly.GetExecutingAssembly());
Console.WriteLine(JsonSerializer.Serialize(documentation));
// Returns:
// 2
// {"Routes":[{"Method":null,"RouteUri":null,"Summary":"Adds A to B.","AuthenticationRequired":false,"Parameters":[{"Name":"a","Type":1,"Summary":"The first number to add."},{"Name":"b","Type":1,"Summary":"The second number to add."}],"PotentialErrors":[{"Name":"NotImplementedException","OccursWhen":"A number is negative"}]}]}
Overriding default behavior
You can override how the documentation generator gets its information by extending DocumentationGenerator
:
public class ExampleDocumentationGenerator : DocumentationGenerator
{
protected override IEnumerable<MethodInfo> FindMethodsToDocument(Assembly assembly)
{
return assembly
.GetTypes()
.FirstOrDefault(t => t == typeof(ExampleApi))!
.GetMethods()
.Where(m => m.GetCustomAttribute<DocSummaryAttribute>() != null);
}
protected override void DocumentRouteHook(MethodInfo method, Route route)
{
Console.WriteLine("Hooked " + method.Name);
route.Method = "GET";
route.RouteUri = '/' + method.Name.ToLower();
}
}
Which will make the example above output:
2
Hooked Add
{"Routes":[{"Method":"GET","RouteUri":"/add","Summary":"Adds A to B.","AuthenticationRequired":false,"Parameters":[{"Name":"a","Type":1,"Summary":"The first number to add."},{"Name":"b","Type":1,"Summary":"The second number to add."}],"PotentialErrors":[{"Name":"NotImplementedException","OccursWhen":"A number is negative"}]}]}
Custom attributes
You can make an attribute extending DocAttribute
to implement custom behavior:
public class DocCustomAttribute : DocAttribute
{
public override void AddDataToRouteDocumentation(MethodInfo method, Route route)
{
route.Summary += "\nCustom behavior!";
}
}
Request/Response bodies
As of v1.1.0, you can now include request/response bodies. You can do this a couple ways:
- A normal string
[DocSummary("Returns the string Hello World!")]
[DocResponseBody("Hello World!")]
public static string HelloWorld() => "Hello World!";
{
"Method": "GET",
"RouteUri": "/helloworld",
"Summary": "Returns the string Hello World!",
"AuthenticationRequired": false,
"Parameters": [],
"PotentialErrors": [],
"ExampleRequestBody": null,
"ExampleResponse": "Hello World!"
}
- Specifying a type to be instantiated
[DocSummary("Adds FirstNumber to SecondNumber.")]
[DocError(typeof(NotImplementedException), "A number is negative")]
[DocRequestBody(typeof(AddBody))]
public static int AddWithBody(AddBody body) => Add(body.FirstNumber, body.SecondNumber);
{
"Method": "GET",
"RouteUri": "/addwithbody",
"Summary": "Adds FirstNumber to SecondNumber.",
"AuthenticationRequired": false,
"Parameters": [],
"PotentialErrors": [
{
"Name": "NotImplementedException",
"OccursWhen": "A number is negative"
}
],
"ExampleRequestBody": {
"FirstNumber": 0,
"SecondNumber": 0
},
"ExampleResponse": null
}
- Specifying a field on a type to be used
[DocSummary("Retrieves the current weather in your area")]
[DocResponseBody(typeof(Weather), nameof(Weather.Example))]
public static Weather GetWeather()
=> new()
{
Temperature = 69,
IsFahrenheit = true
};
{
"Method": "GET",
"RouteUri": "/getweather",
"Summary": "Retrieves the current weather in your area",
"AuthenticationRequired": false,
"Parameters": [],
"PotentialErrors": [],
"ExampleRequestBody": null,
"ExampleResponse": {
"Temperature": 21,
"IsFahrenheit": false
}
}
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. 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. |
.NET Core | netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.1 is compatible. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
-
.NETStandard 2.1
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.