API-Dokumentation

Die Sisk.Documenting‑Erweiterung ermöglicht es Ihnen, automatisch API‑Dokumentation für Ihre Sisk‑Anwendung zu erzeugen. Sie nutzt Ihre Code‑Struktur und Attribute, um eine umfassende Dokumentations‑Website zu erstellen, die den Export ins Open API‑Format (Swagger) unterstützt.

Da dieses Paket noch nicht auf NuGet verfügbar ist, müssen Sie den Quellcode direkt in Ihr Projekt einbinden oder es als Projekt‑Abhängigkeit referenzieren. Sie können den Quellcode hier abrufen.

Um Sisk.Documenting zu verwenden, müssen Sie es in Ihrem Application‑Builder registrieren und Ihre Routinen‑Handler mit Dokumentations‑Attributen versehen.

Registrieren der Dokumentationsgenerierung #

Verwenden Sie die Erweiterungsmethode UseApiDocumentation auf Ihrem HttpServerHostContextBuilder, um die generierte API‑Dokumentation über denselben Router bereitzustellen, der Ihre Anwendung bedient.

using Sisk.Documenting;
using Sisk.Documenting.Exporters;

// ...

host.UseApiDocumentation(
    context: new ApiGenerationContext()
    {
        ApplicationName = "My Application",
        ApplicationDescription = "Description of my application.",
        ApplicationVersion = "1.0.0"
    },
    routerPath: "/api/docs",
    exporter: new OpenApiExporter() { ServerUrls = ["http://localhost:5555/"] });

• context: Definiert Metadaten über Ihre Anwendung, wie Name, Beschreibung und Version.
• routerPath: Der URL‑Pfad, unter dem die Dokumentations‑Benutzeroberfläche (oder JSON) erreichbar ist.
• exporter: Konfiguriert, wie die Dokumentation exportiert wird. Der OpenApiExporter ermöglicht die Unterstützung von Open API (Swagger).

Dokumentieren von Endpunkten #

Sie können Ihre Endpunkte mit den Attributen [ApiEndpoint] und [ApiQueryParameter] auf Ihren Routinen‑Handler‑Methoden beschreiben.

ApiEndpoint #

Das [ApiEndpoint]‑Attribut erlaubt es Ihnen, eine Beschreibung für den Endpunkt anzugeben.

[ApiEndpoint(Description = "Returns a greeting message.")]
public HttpResponse Index(HttpRequest request) { ... }

ApiQueryParameter #

Das [ApiQueryParameter]‑Attribut dokumentiert Abfrage‑String‑Parameter, die der Endpunkt akzeptiert.

[ApiQueryParameter(name: "name", IsRequired = false, Description = "The name of the person to greet.", Type = "string")]
public HttpResponse Index(HttpRequest request) { ... }

• name: Der Name des Abfrage‑Parameters.
• IsRequired: Gibt an, ob der Parameter zwingend erforderlich ist.
• Description: Eine menschenlesbare Beschreibung des Parameters.
• Type: Der erwartete Datentyp (z. B. „string“, „int“).

ApiEndpoint #

Annotiert einen Endpunkt mit allgemeinen Informationen.

• Name (string, required in constructor): Der Name des API‑Endpunkts.
• Description (string): Eine kurze Beschreibung dessen, was der Endpunkt tut.
• Group (string): Ermöglicht das Gruppieren von Endpunkten (z. B. nach Controller oder Modul).
• InheritDescriptionFromXmlDocumentation (bool, default: true): Wenn true, wird versucht, die XML‑Dokumentations‑Zusammenfassung der Methode zu verwenden, falls Description nicht gesetzt ist.

ApiHeader #

Dokumentiert einen spezifischen HTTP‑Header, den der Endpunkt erwartet oder verwendet.

• HeaderName (string, required in constructor): Der Schlüssel des Headers (z. B. „Authorization“).
• Description (string): Beschreibt den Zweck des Headers.
• IsRequired (bool): Gibt an, ob der Header für die Anfrage zwingend erforderlich ist.

ApiParameter #

Definiert einen generischen Parameter für den Endpunkt, häufig verwendet für Formularfelder oder Body‑Parameter, die nicht durch andere Attribute abgedeckt sind.

• Name (string, required in constructor): Der Name des Parameters.
• TypeName (string, required in constructor): Der Datentyp des Parameters (z. B. „string“, „int“).
• Description (string): Eine Beschreibung des Parameters.
• IsRequired (bool): Gibt an, ob der Parameter zwingend erforderlich ist.

ApiParametersFrom #

Erzeugt automatisch Parameter‑Dokumentation aus den Eigenschaften einer angegebenen Klasse oder eines Typs.

• Type (Type, required in constructor): Der Klassen‑Type, aus dem die Eigenschaften reflektiert werden sollen.

ApiPathParameter #

Dokumentiert eine Pfad‑Variable (z. B. in /users/{id}).

• Name (string, required in constructor): Der Name des Pfad‑Parameters.
• Description (string): Beschreibt, was der Parameter repräsentiert.
• Type (string): Der erwartete Datentyp.

ApiQueryParameter #

Dokumentiert einen Abfrage‑String‑Parameter (z. B. ?page=1).

• Name (string, required in constructor): Der Schlüssel des Abfrage‑Parameters.
• Description (string): Beschreibt den Parameter.
• Type (string): Der erwartete Datentyp.
• IsRequired (bool): Gibt an, ob der Abfrage‑Parameter zwingend vorhanden sein muss.

ApiRequest #

Beschreibt den erwarteten Request‑Body.

• Description (string, required in constructor): Eine Beschreibung des Request‑Bodies.
• Example (string): Ein Roh‑String, der ein Beispiel des Request‑Bodies enthält.
• ExampleLanguage (string): Die Sprache des Beispiels (z. B. „json“, „xml“).
• PayloadType (Type): Falls gesetzt, werden Beispiel und Schema automatisch aus diesem Typ generiert, sofern die konfigurierten Kontext‑Handler dies unterstützen.

ApiResponse #

Beschreibt eine mögliche Antwort des Endpunkts.

• StatusCode (HttpStatusCode, required in constructor): Der zurückgegebene HTTP‑Statuscode (z. B. HttpStatusCode.OK).
• Description (string): Beschreibt die Bedingung für diese Antwort.
• Example (string): Ein Roh‑String, der ein Beispiel des Antwort‑Bodies enthält.
• ExampleLanguage (string): Die Sprache des Beispiels.
• PayloadType (Type): Falls gesetzt, werden Beispiel und Schema automatisch aus diesem Typ generiert, sofern die konfigurierten Kontext‑Handler dies unterstützen.

Typ-Handler #

Typ‑Handler sind dafür verantwortlich, Ihre .NET‑Typen (Klassen, Enums usw.) in Dokumentations‑Beispiele zu konvertieren. Das ist besonders nützlich, um automatische Request‑ und Response‑Body‑Beispiele basierend auf Ihren Datenmodellen zu erzeugen.

Diese Handler werden innerhalb des ApiGenerationContext konfiguriert.

using Sisk.Documenting.Content;

var context = new ApiGenerationContext()
{
    // ...
    BodyExampleTypeHandler = new JsonContentTypeHandler(),
    ParameterExampleTypeHandler = new JsonContentTypeHandler(),
    ContentSchemaTypeHandler = new JsonContentTypeHandler()
};

JsonContentTypeHandler #

Der JsonContentTypeHandler ist ein integrierter Handler, der JSON‑Beispiele, Parameter‑Beispiele und JSON‑Schemas erzeugt. Er implementiert IExampleBodyTypeHandler, IExampleParameterTypeHandler und IContentSchemaTypeHandler.

Er kann mit spezifischen JsonSerializerOptions oder IJsonTypeInfoResolver angepasst werden, um die Serialisierungs‑Logik Ihrer Anwendung zu berücksichtigen.

var jsonHandler = new JsonContentTypeHandler(new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
});

context.BodyExampleTypeHandler = jsonHandler;
context.ParameterExampleTypeHandler = jsonHandler;
context.ContentSchemaTypeHandler = jsonHandler;

Custom Type Handlers #

Sie können eigene Handler implementieren, um andere Formate (wie XML) zu unterstützen oder um zu steuern, wie Beispiele generiert werden.

IExampleBodyTypeHandler #

Implementieren Sie dieses Interface, um Body‑Beispiele für Request‑ und Response‑Typen zu erzeugen.

public class XmlExampleTypeHandler : IExampleBodyTypeHandler
{
    public BodyExampleResult? GetBodyExampleForType(Type type)
    {
        // Generate XML string for the type
        string xmlContent = MyXmlGenerator.Generate(type);

        return new BodyExampleResult(xmlContent, "xml");
    }
}

IExampleParameterTypeHandler #

Implementieren Sie dieses Interface, um detaillierte Parameter‑Beschreibungen aus einem Typ zu erzeugen (verwendet von [ApiParametersFrom]).

public class CustomParameterHandler : IExampleParameterTypeHandler
{
    public ParameterExampleResult[] GetParameterExamplesForType(Type type)
    {
        var properties = type.GetProperties();
        var examples = new List<ParameterExampleResult>();

        foreach (var prop in properties)
        {
            examples.Add(new ParameterExampleResult(
                name: prop.Name,
                typeName: prop.PropertyType.Name,
                isRequired: true,
                description: "Generated description"
            ));
        }

        return examples.ToArray();
    }
}

Exporters #

Exporter sind dafür verantwortlich, die gesammelten API‑Dokumentations‑Metadaten in ein bestimmtes Format zu konvertieren, das von anderen Tools konsumiert oder dem Benutzer angezeigt werden kann.

OpenApiExporter #

Der standardmäßig bereitgestellte Exporter ist der OpenApiExporter, der eine JSON‑Datei gemäß der OpenAPI Specification 3.0.0 erzeugt.

new OpenApiExporter()
{
    OpenApiVersion = "3.0.0",
    ServerUrls = new[] { "http://localhost:5555" },
    Contact = new OpenApiContact()
    {
        Name = "Support",
        Email = "[email protected]",
        Url = "https://example.com/support"
    },
    License = new OpenApiLicense()
    {
        Name = "MIT",
        Url = "https://opensource.org/licenses/MIT"
    },
    TermsOfService = "https://example.com/terms"
}

Creating a Custom Exporter #

Sie können Ihren eigenen Exporter erstellen, indem Sie das Interface IApiDocumentationExporter implementieren. Damit können Sie die Dokumentation in Formaten wie Markdown, HTML, Postman Collection oder einem anderen benutzerdefinierten Format ausgeben.

Das Interface verlangt die Implementierung einer einzigen Methode: ExportDocumentationContent.

using Sisk.Core.Http;
using Sisk.Documenting;

public class MyCustomExporter : IApiDocumentationExporter
{
    public HttpContent ExportDocumentationContent(ApiDocumentation documentation)
    {
        // 1. Process the documentation object
        var sb = new StringBuilder();
        sb.AppendLine($"# {documentation.ApplicationName}");

        foreach(var endpoint in documentation.Endpoints)
        {
            sb.AppendLine($"## {endpoint.Method} {endpoint.Path}");
            sb.AppendLine(endpoint.Description);
        }

        // 2. Return the content as an HttpContent
        return new StringContent(sb.ToString(), Encoding.UTF8, "text/markdown");
    }
}

Dann verwenden Sie ihn einfach in Ihrer Konfiguration:

host.UseApiDocumentation(
    // ...
    exporter: new MyCustomExporter()
);

Full Example #

Unten finden Sie ein vollständiges Beispiel, das zeigt, wie Sisk.Documenting eingerichtet und ein einfacher Controller dokumentiert wird.

using Sisk.Core.Entity;
using Sisk.Core.Http;
using Sisk.Core.Routing;
using Sisk.Documenting;
using Sisk.Documenting.Annotations;
using Sisk.Documenting.Exporters;

using var host = HttpServer.CreateBuilder(5555)
    .UseCors(CrossOriginResourceSharingHeaders.CreatePublicContext())
    .UseApiDocumentation(
        context: new ApiGenerationContext()
        {
            ApplicationName = "My application",
            ApplicationDescription = "It greets someone."
        },
        routerPath: "/api/docs",
        exporter: new OpenApiExporter() { ServerUrls = ["http://localhost:5555/"] })
    .UseRouter(router =>
    {
        router.MapInstance(new MyController());
    })
    .Build();

await host.StartAsync();

class MyController
{
    [RouteGet]
    [ApiEndpoint(Description = "Returns a greeting message.")]
    [ApiQueryParameter(name: "name", IsRequired = false, Description = "The name of the person to greet.", Type = "string")]
    public HttpResponse Index(HttpRequest request)
    {
        string? name = request.Query["name"].MaybeNullOrEmpty() ?? "world";
        return new HttpResponse($"Hello, {name}!");
    }
}

In diesem Beispiel liefert das Aufrufen von /api/docs die generierte Dokumentation für die API „My application“ und beschreibt den GET /‑Endpunkt sowie dessen name‑Parameter.