Praxis
Spezifikation mit Include
Mit Asciidoc und der include-Direktive ist es sehr
einfach, ganze Dateien oder Teile des Codes in die
Produktdokumentation im Wiki
einzubetten. Die Datei application.yaml einer
Spring-Boot-Anwendung zeigt die Grundkonfiguration der
Anwendung. Das Deployment einer Anwendung
wird durch die yml-Datei der
Ingress-Konfiguration sehr gut gezeigt. Das sind
nur zwei Beispiele. Praktisch jede gut lesbare
Quelldatei kann zu einer aussagekräftigen
Spezifikation werden.
Mit diesen Fähigkeiten hebt sich das Format Asciidoc von anderen Markdown-Dialekten ab. Code und Code-Fragmente werden dort um erklärende Hinweise ergänzt, wo der Code alleine nicht klar genug ist. Oft reichen dafür Links zu Online-Hilfen im Internet.
Bitte hier Klicken, um den Quelltext anzuzeigen
= Wetter API
== Konfiguration
Das Service hat folgende Grundeinstellungen:
[source,text]
----
include::{srcdir}/main/resources/application.properties[]
----
TIP: Siehe
https://spring.io/projects/spring-boot
für mehr Informationen.
== Deployment
Das Service stellt folgende Operationen zur Verfügung:
[source,text]
----
include::{srcdir}/helm/templates/ingress.yml[tag=path]
----
TIP: Siehe
https://helm.sh
für mehr Informationen.
Es gilt die Regel, dass in jedem Code-Repository ein Ordner
doc und die primäre Asciidoc-Datei
service.adoc
existiert. Damit können Entwickler Ihre
Spezifikation auf mehrere Asciidoc-Dateien aufteilen.
Das erleichtert die Teamarbeit und verbessert die
Übersichtlichkeit. Die primäre Asciidoc-Datei wird
bei der Freigabe der Implementierung als Unterseite im
Baustein
Service
in das Wiki hochgeladen.
Das Ergebnis ist eine Produktdokumentation, die in einem großen Maß aus Code besteht. Code, der in der veröffentlichten Form tatsächlich als Teil der Software ausgeführt wird. Hinweise und Erläuterungen im Wiki erklären, warum es den Code gibt. Der Code selbst zeigt, wie die konkrete Lösung aussieht.
Asciidoc(tor).
Für Qualität.
Praxis
Spezifikation mit Spring REST-Docs
In diesem Architekturstil besteht das IT-System aus einer Menge von Diensten, die eine Abfrageschnittstelle (engl. query interface) mit einem REST-API anbieten. In diesem Architekturstil besteht eine starke Laufzeitkopplung zwischen den Diensten und eine starke Abhängigkeit durch gemeinsam genutzte Informationsobjekte.
Spring REST-Docs kombiniert handgeschriebene und generierte Asciidoc-Dateien zu einer API-Dokumentation. Ein Spring MVC-Test erstellt bei der Ausführung Asciidoc-Fragmente, die das REST-API vollständig dokumentieren. Der Ansatz stellt sicher, dass die Dokumentation nur erstellt werden kann, wenn der Test erfolgreich war. Gleichzeitig wird sichergestellt, dass genau das dokumentiert wird, was auch implementiert wurde.
Die Verwendung von Spring REST-Docs erweitert den Ansatz der Spezifikation mit Asciidoc. Die Spezifikation besteht aus einer Asciidoc-Datei als Rahmendokument. Dort beschreiben die Entwickler Besonderheiten und Regeln der Implementierung als Text oder sie inkludieren lesbare Teile vom Code. Zusätzlich werden die von Spring REST-Docs generierten Fragmente eingefügt.
Bitte hier Klicken, um den Quelltext anzuzeigen
= Wetter API
== Konfiguration
Das Service hat folgende Grundeinstellungen:
[source,text]
----
include::{srcdir}/main/resources/application.properties[]
----
TIP: Siehe
https://spring.io/projects/spring-boot
für mehr Informationen.
== Operationen
Das Service stellt folgende Operationen zur Verfügung:
=== GET /wetter
Die Operation liefert alle Datensätze einer
Wetterstation.
Der Status-Code ist im Erfolgsfall 200 (ok).
Der Status-Code ist 204 (no content), wenn
die Wetterstation unbekannt ist.
Der Status-Code ist 404 (not found), wenn
keine Daten vorliegen.
==== Request
include::{snippets}/wetter/http-request.adoc[]
==== Response
include::{snippets}/wetter/http-response.adoc[]
==== CURL
include::{snippets}/wetter/curl-request.adoc[]
=== POST /wetter
Die Operation speichert einen Datensatz einer
Wetterstation.
Der Status-Code ist im Erfolgsfall 200 (ok).
Der Status-Code ist 204 (no content), wenn
die Wetterstation unbekannt ist.
Der Status-Code ist 406 (not acceptable),
wenn die Daten fehlerhaft sind.
==== Request
include::{snippets}/wetter/http-request.adoc[]
==== Response
include::{snippets}/wetter/http-response.adoc[]
==== CURL
include::{snippets}/wetter/curl-request.adoc[]
Es gilt die Regel, dass in jedem Code-Repository ein Ordner
doc
und die primäre Asciidoc-Datei
service.adoc
existiert. Die Spezifikation für den Dienst besteht aus der
primären Asciidoc-Datei als Rahmendokument, in
der alle mit Spring REST Docs erzeugten Asciidoc-Fragmente
an passender Stelle eingefügt wurden. Die primäre
Asciidoc-Datei wird bei der Freigabe der
Implementierung als Unterseite im Baustein
Service
in das Wiki hochgeladen.
Der Aufwand für die Pflege der Spezifikation durch das Team wird dadurch reduziert. Gleichzeitig steigt die Qualität der Spezifikation, weil sie nicht nur zu großen Teilen automatisch generiert, sondern auch getestet wurde.
Praxis
Spezifikation mit Javadoc
Eine Java-Klasse kann durch spezielle Kommentare im Quelltext angereichert werden. Hierfür kommen Javadoc-Kommentare zum Einsatz, die dazu dienen, die Klasse, seine Methoden und Felder näher zu beschreiben. Javadoc wird automatisch als Teil des Quelltextes versioniert.
Das Javadoc-Tool ist ein Dokumentationswerkzeug aus dem JDK, das aus Java-Code mit Javadoc-Kommentaren automatisch HTML-Dateien erstellt. Neben der Standardausgabe in HTML sind alternative Ausgaben durch spezielle Doclets möglich.
Die Verwendung von Javadoc-Kommentaren als Spezifikation lässt sich am Beispiel eines Informationsobjektes für die Daten einer Wetterstation zeigen. Es beschreibt das Wetter mit Angaben zu Regen, Temperatur und Windstärke zum Zeitpunkt der Messung.
Bitte hier Klicken, um den Quelltext anzuzeigen
/**
* Ergebnis der Messung einer Wetterstation.
*/
@Entity
@Table(name = "WETTER")
public class Wetter extends AbstractEntity {
/**
* Die eindeutige Kennung der Wetterstation.
*/
@Size(max = 50)
@NotNull
@Column(name = "KENNUNG")
private String kennung;
/**
* Der Wert ist true, wenn es zum Zeitpunkt
* der Messung regnet.
*/
@NotNull
@Column(name = "REGEN")
private boolean regen;
/**
* Die Temperatur in Grad Celsius zum Zeitpunkt
* der Messung.
*/
@NotNull
@Column(name = "TEMP")
private double temp;
/**
* Die Kategorie der Windstärke zum Zeitpunkt
* der Messung.
*/
@NotNull
@Column(name = "WIND")
@Enumerated(EnumType.STRING)
private Windkategorie wind;
}
Es gilt die Regel, dass in jedem Code-Repository ein Ordner
doc
und eine primäre Asciidoc-Datei für jedes
Informationsobjekt existiert. Die Spezifikation
für das Informationsobjekt besteht aus der primären
Asciidoc-Datei als Rahmendokument, in der alle von
einem Doclet erzeugten Asciidoc-Fragmente an
passender Stelle eingefügt wurden. Die primäre
Asciidoc-Datei wird bei der Freigabe der
Implementierung als Unterseite im Baustein
Entity
in das Wiki hochgeladen.
Der Aufwand für die Pflege der Spezifikation durch das Team wird dadurch reduziert. Gleichzeitig steigt die Qualität der Spezifikation, weil Wissen direkt aus dem Code übernommen wird.
Praxis
Spezifikation mit Avro
In diesem Architekturstil besteht das IT-System aus einer Menge von Diensten, die Daten event-basiert verarbeiten (engl. streaming) und über Nachrichtenkanäle asynchron verteilen (engl. broadcast). In diesem Architekturstil besteht eine schwache Laufzeitkopplung zwischen den Diensten. Die Abhängigkeit durch gemeinsam genutzte Nachrichtenobjekte kann mit dem Einsatz einer Schemaevolution reduziert werden.
Avro aus dem Apache-Universum ist eine von vielen Lösungen für eine sprachneutrale Datenserialisierung. Mit Avro werden Daten mit einem Schema beschrieben. Avro unterstützt primitive und komplexe Typen und Listen davon. Die Schema-Datei kann wie Quelltext versioniert werden.
Die Verwendung von Avro-Schemadateien als Spezifikation lässt sich am Beispiel eines Datensatzes einer Wetterstation zeigen. Das Nachrichtenobjekt beschreibt das Wetter mit Angaben zu Regen, Temperatur und Windstärke zum Zeitpunkt der Messung.
Bitte hier Klicken, um den Quelltext anzuzeigen
{
"name": "WetterEvent",
"type": "record",
"fields": [
{
"name": "meta",
"type": {
"name": "Meta",
"type": "record",
"fields": [
{
"name": "id",
"type": "string"
},
{
"name": "correlation",
"type": {
"type": "array",
"items": "string"
}
},
{
"name": "created",
"type": "string"
}
]
}
},
{
"name": "data",
"type": {
"name": "WetterData",
"type": "record",
"fields": [
{
"name": "kennung",
"type": "string",
"doc": "Die eindeutige Kennung der Wetterstation."
},
{
"name": "regen",
"type": "boolean",
"doc": "Der Wert ist true, wenn es zum Zeitpunkt der Messung regnet."
},
{
"name": "temp",
"type": "double",
"doc": "Die Temperatur in Grad Celsius zum Zeitpunkt der Messung."
},
{
"name": "wind",
"type": {
"type": "enum",
"name": "Windkategorie",
"symbols": [
"UNBEKANNT",
"FLAUTE",
"BRISE",
"WIND",
"STURM",
"ORKAN"
]
},
"doc": "Die Kategorie der Windstärke zum Zeitpunkt der Messung.",
"default": "UNBEKANNT"
}
]
}
}
]
}
Die Avro-Schemadatei ist bereits eine lesbare Spezifikation. Sie kann so wie sie im Code-Repository vorliegt im Wiki als Unterseite im Baustein Event veröffentlicht werden. Struktur und Datentypen des Events werden im Rahmen der Möglichkeiten von Avro syntaktisch beschrieben. Mit dem doc-Element gibt der Entwickler noch zusätzliche semantische Informationen. Das default-Element kann auch zur Festlegung des Standardertes verwendet werden.
Der Aufwand für die Pflege der Spezifikation durch das Team wird dadurch minimiert. Gleichzeitig steigt die Qualität der Spezifikation, weil Code direkt als Dokumentation übernommen wird.