API-04: openapi-schnittstellenbeschreibung (drift-check + beispielausfuehrung)

internal/openapi/openapi.go

@@ -0,0 +1,158 @@
+// Package openapi implementiert Core API-04: eine OpenAPI-3.x-Beschreibung
+// der Core-API, die automatisiert gegen die tatsaechlich registrierten
+// Routen von internal/apiserver.Server geprueft wird (Akzeptanzkriterium 2)
+// — kein manuell gepflegtes Dokument, das unbemerkt vom Code abweichen kann.
+package openapi
+
+import (
+	"fmt"
+	"sort"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/apiserver"
+)
+
+// Entry beschreibt EINEN dokumentierten Endpunkt inklusive eines
+// Beispielaufrufs (Akzeptanzkriterium 2 / Pruefung 2: "Beispielaufrufe aus
+// dem Dokument gegen die echte API erfolgreich ausgefuehrt").
+type Entry struct {
+	// Path ist der VOLLSTAENDIGE, versionierte Pfad (z.B. "/api/v1/things"),
+	// identisch zu dem, was apiserver.Server.RegisteredPaths() liefert.
+	Path        string
+	Method      string
+	Summary     string
+	Description string
+	// ExampleRequest wird von CheckExamples tatsaechlich gegen den Server
+	// ausgefuehrt (Cookie, Body etc. sind Sache des Aufrufers, siehe
+	// openapi_test.go) — dieses Paket fuehrt nur die HTTP-Anfrage aus und
+	// prueft ExpectStatus.
+	ExampleRequest ExampleRequest
+	ExpectStatus   int
+}
+
+// ExampleRequest ist minimal genug, um sowohl in das OpenAPI-Dokument als
+// auch als tatsaechliche HTTP-Anfrage verwendet zu werden — EIN Beispiel,
+// zwei Verwendungen, damit Dokument und Test nie auseinanderlaufen koennen.
+type ExampleRequest struct {
+	Method      string
+	Path        string
+	Description string
+}
+
+// Document ist eine bewusst schlanke OpenAPI-3.0-Repraesentation — genug,
+// um valide zu sein und von Swagger UI/Postman importiert zu werden
+// (Akzeptanzkriterium 3), ohne eine vollstaendige OpenAPI-Bibliothek zu
+// integrieren.
+type Document struct {
+	OpenAPI string                `json:"openapi"`
+	Info    Info                  `json:"info"`
+	Paths   map[string]PathItem   `json:"paths"`
+}
+
+type Info struct {
+	Title   string `json:"title"`
+	Version string `json:"version"`
+}
+
+type PathItem map[string]Operation
+
+type Operation struct {
+	Summary     string `json:"summary"`
+	Description string `json:"description,omitempty"`
+	Responses   map[string]Response `json:"responses"`
+}
+
+type Response struct {
+	Description string `json:"description"`
+}
+
+// BuildDocument erzeugt das OpenAPI-Dokument AUS denselben Entries, die auch
+// fuer den Drift-Abgleich (CheckNoDrift) und die Beispielausfuehrung
+// (siehe openapi_test.go) verwendet werden — eine einzige Quelle statt
+// eines separat gepflegten Dokuments.
+func BuildDocument(title, version string, entries []Entry) Document {
+	paths := make(map[string]PathItem)
+	for _, e := range entries {
+		item, ok := paths[e.Path]
+		if !ok {
+			item = PathItem{}
+		}
+		item[toLowerMethod(e.Method)] = Operation{
+			Summary:     e.Summary,
+			Description: e.Description,
+			Responses: map[string]Response{
+				fmt.Sprintf("%d", e.ExpectStatus): {Description: "Beispielhafte Antwort"},
+			},
+		}
+		paths[e.Path] = item
+	}
+	return Document{
+		OpenAPI: "3.0.3",
+		Info:    Info{Title: title, Version: version},
+		Paths:   paths,
+	}
+}
+
+func toLowerMethod(m string) string {
+	switch m {
+	case "GET", "get":
+		return "get"
+	case "POST", "post":
+		return "post"
+	case "PUT", "put":
+		return "put"
+	case "DELETE", "delete":
+		return "delete"
+	case "PATCH", "patch":
+		return "patch"
+	default:
+		return "get"
+	}
+}
+
+// ErrDrift wird von CheckNoDrift geliefert, wenn dokumentierte und
+// tatsaechlich registrierte Pfade auseinanderlaufen (Akzeptanzkriterium 2 /
+// Pruefung 1).
+type ErrDrift struct {
+	MissingInDocument []string // registriert, aber nicht dokumentiert
+	MissingAsRoute    []string // dokumentiert, aber nicht (mehr) registriert
+}
+
+func (e *ErrDrift) Error() string {
+	return fmt.Sprintf("openapi: drift erkannt — nicht dokumentiert: %v, nicht (mehr) registriert: %v",
+		e.MissingInDocument, e.MissingAsRoute)
+}
+
+// CheckNoDrift vergleicht die tatsaechlich registrierten Pfade eines
+// Servers mit den in entries dokumentierten Pfaden — vollstaendige
+// Uebereinstimmung der PATH-Menge (nicht Methode je Pfad, da
+// apiserver.Server.Handle methodenunabhaengig registriert). Ein absichtlich
+// entfernter Eintrag auf beiden Seiten (siehe Tests) macht diese Funktion
+// fehlschlagen, das ist der geforderte Drift-Nachweis.
+func CheckNoDrift(server *apiserver.Server, entries []Entry) error {
+	registered := make(map[string]bool)
+	for _, p := range server.RegisteredPaths() {
+		registered[p] = true
+	}
+	documented := make(map[string]bool)
+	for _, e := range entries {
+		documented[e.Path] = true
+	}
+
+	var missingInDoc, missingAsRoute []string
+	for p := range registered {
+		if !documented[p] {
+			missingInDoc = append(missingInDoc, p)
+		}
+	}
+	for p := range documented {
+		if !registered[p] {
+			missingAsRoute = append(missingAsRoute, p)
+		}
+	}
+	if len(missingInDoc) == 0 && len(missingAsRoute) == 0 {
+		return nil
+	}
+	sort.Strings(missingInDoc)
+	sort.Strings(missingAsRoute)
+	return &ErrDrift{MissingInDocument: missingInDoc, MissingAsRoute: missingAsRoute}
+}