Methode

Spezifi­kation mit Asciidoc

Ascii­doc ist eine leicht­gewicht­ige Aus­zeich­nungs­sprache für eine text­basierte Doku­men­ten­generie­rung. Eine Ascii­doc-Datei kann wie Quell­text ent­wickelt und versio­niert werden.

Ascii­doctor ist ein belieb­ter Text­prozes­sor, der eine Ascii­doc-Datei u.a. in die For­mate HTML5, EPUB3 und PDF umwan­deln kann. Ascii­doctor unter­stützt auch text­basierte Dia­gramme mit GraphViz oder PlantUML.

Die Ver­wendung von Ascii­doc als Format für die Spezi­fikation lässt sich am Bei­spiel eines Dienstes zeigen. Der Dienst bietet ein REST-API an, um Daten­sätze mit Anga­ben zu Regen, Tempera­tur und Wind­stärke zum Zeit­punkt zu speichern und abzu­fragen.

Bitte hier Klicken, um den Quelltext anzuzeigen
@RestController
@RequestMapping("/wetter")
public class WetterController {

  @RequestMapping(method = RequestMethod.POST)
  public void createWetter(@RequestBody Wetter wetter) {
    this.wetterRepository.create(wetter);
  }
    
  @RequestMapping(method = RequestMethod.GET)
  public Collection findAllWetter(String kennung) {
    return this.wetterRepository.findAllByKennung(String kennung);
  }        
}

Die Spezifi­kation des Dienstes besteht aus einer zen­tra­len Ascii­doc-Datei. Dort beschrei­ben die Ent­wick­ler Besonder­heiten und Regeln der Imple­mentierung als Text oder sie inklu­dieren les­bare Teile vom Code.

Bitte hier Klicken, um den Quelltext anzuzeigen
= Wetter API

== Konfiguration

[source,text]
----
include::{srcdir}/main/resources/application.properties[]
----

== Operationen

Das Service stellt folgende Operationen zur Verfügung.

|===
|Operation |Name |Funktion |Status

|GET
|/wetter?kennung=<String>
|Die Operation liefert alle Datensätze einer Wetterstation.
|200=ok +
204 (Wetterstation unbekannt) +
404 (Keine Daten)

|POST
|/wetter
|Die Operation speichert einen Datensatz einer Wetterstation.
|200=ok +
204 (Wetterstation unbekannt) +
406 (Falsche Daten)
|===

Es gilt die Regel, dass in jedem Code-Reposi­tory ein Ordner doc und die primäre Ascii­doc-Datei service.adoc exis­tiert. Damit können Ent­wick­ler Ihre Spezifi­kation auf mehrere Ascii­doc-Dateien auf­teilen. Das erleich­tert die Team­arbeit und ver­bessert die Über­sicht­lich­keit. Die primäre Ascii­doc-Datei wird bei der Frei­gabe der Imple­mentierung als Unter­seite im Bau­stein Service in das Wiki hoch­geladen.


Methode

Spezifi­kation mit Spring REST-Docs

Spring REST-Docs kombi­niert hand­geschrie­bene und gene­rierte Ascii­doc-Dateien zu einer API-Doku­mentation. Ein Spring MVC-Test erstellt bei der Aus­führung Ascii­doc-Frag­mente , die das REST-API voll­stän­dig doku­mentieren. Der Ansatz stellt sicher, dass die Doku­mentation nur erstellt werden kann, wenn der Test erfolg­reich war. Gleich­zeitig wird sicher­gestellt, dass genau das doku­mentiert wird, was auch imple­men­tiert wurde.

Die Ver­wendung von Spring REST-Docs erwei­tert den Ansatz der Spezifi­kation mit Ascii­doc. Die Spezifi­kation besteht aus einer Ascii­doc-Datei als Rah­men­doku­ment. Dort beschrei­ben die Ent­wick­ler Besonder­heiten und Regeln der Imple­mentierung als Text oder sie inkludieren lesbare Teile vom Code. Zusätz­lich werden die von Spring REST-Docs gene­rierten Frag­mente einge­fügt.

Bitte hier Klicken, um den Quelltext anzuzeigen
= Wetter API

== Konfiguration

[source,text]
----
include::{srcdir}/main/resources/application.properties[]
----

== 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-Reposi­tory ein Ordner doc und die primäre Ascii­doc-Datei service.adoc exis­tiert. Die Spezifi­­kation für den Dienst besteht aus der pri­mären Ascii­­doc-Datei als Rah­men­­doku­­ment, in der alle mit Spring REST Docs erzeugten Ascii­doc-Frag­mente an passen­der Stelle ein­gefügt wurden. Die primäre Ascii­doc-Datei wird bei der Frei­gabe der Imple­mentierung als Unter­seite im Bau­stein Service in das Wiki hoch­geladen.

Der Auf­­wand für die Pflege der Spezifi­­kation durch das Team wird dadurch redu­ziert. Gleich­zeitig steigt die Quali­tät der Spezifi­kation, weil sie nicht nur auto­matisch gene­riert, sondern auch getes­tet wurde.


Methode

Spezifi­kation mit Java­doc

Eine Java-Klasse kann durch spezi­elle Kommen­tare im Quell­text ange­reichert werden. Hier­für kommen Java­doc-Kommen­tare zum Ein­satz, die dazu dienen, die Klasse, seine Methoden und Felder näher zu beschrei­ben. Java­doc wird automatisch als Teil des Quell­textes versio­niert.

Das Java­doc-Tool ist ein Doku­mentations­werk­zeug aus dem JDK, das aus Java-Code mit Java­doc-Kommen­taren auto­matisch HTML-Dateien erstellt. Neben der Standard­aus­gabe in HTML sind alter­native Aus­gaben durch spezi­elle Doclets mög­lich.

Die Ver­wendung von Java­doc-Kommen­taren als Spezi­fikation lässt sich am Bei­spiel eines Infor­mations­objek­tes für die Daten einer Wetter­station zeigen. Es beschreibt das Wetter mit Anga­ben zu Regen, Tempera­tur und Wind­stärke zum Zeit­punkt 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-Reposi­tory ein Ordner doc und eine primäre Ascii­doc-Datei für jedes Infor­mations­objekt exis­tiert. Die Spezifi­­kation für das Infor­mations­objekt besteht aus der pri­mären Ascii­­doc-Datei als Rah­men­­doku­­ment, in der alle von einem Doclet erzeug­ten Ascii­doc-Frag­mente an passen­der Stelle ein­gefügt wurden. Die primäre Ascii­doc-Datei wird bei der Frei­gabe der Imple­mentierung als Unter­seite im Bau­stein Entity in das Wiki hoch­geladen.

Der Auf­­wand für die Pflege der Spezifi­­kation durch das Team wird dadurch redu­ziert. Gleich­zeitig steigt die Quali­tät der Spezifi­kation, weil Wissen direkt aus dem Code über­nommen wird.


Methode

Spezifi­kation mit Avro

Avro aus dem Apache-Uni­ver­sum ist eine von vielen Lösungen für eine sprach­neu­trale Daten­seriali­sierung. Mit Avro werden Daten mit einem Schema beschrie­ben. Avro unter­stützt primi­tive und komp­lexe Typen und Listen davon. Die Schema-Datei kann wie Quell­text versio­niert werden.

Die Ver­wendung von Avro-Schema­dateien als Spezi­fikation lässt sich am Bei­spiel eines Daten­satzes einer Wetter­station zeigen. Das Nach­richten­objekt beschreibt das Wetter mit Anga­ben zu Regen, Tempera­tur und Wind­stärke zum Zeit­punkt 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-Schema­datei ist bereits eine les­bare Spezi­fikation. Sie kann so wie sie im Code-Reposi­tory vor­liegt im Wiki als Unter­seite im Bau­stein Event ver­öffent­licht werden. Struk­tur und Daten­typen des Events werden im Rahmen der Mög­lich­keiten von Avro syntak­tisch beschrie­ben. Mit dem doc-Ele­ment gibt der Ent­wick­ler noch zusätz­liche seman­tische Infor­mationen. Das default-Element kann auch zur Fest­legung des Stan­dard­ertes ver­wendet werden.

Der Auf­­wand für die Pflege der Spezifi­­kation durch das Team wird dadurch mini­­miert. Gleich­zeitig steigt die Quali­tät der Spezifi­kation, weil Code direkt als Doku­mentation über­nommen wird.