Java >> Java Tutorial >  >> Tag >> maven

Generieren von HTML-Dokumentation aus RAML-Dokumenten mit Maven

maven

Die RESTful API Modeling Language (RAML) ist eine YAML-basierte Sprache, die zur Beschreibung von REST(ful)-APIs verwendet wird.

Ich mag die RAML-Syntax, weil sie textbasiert, vielseitig und einfach zu verwenden ist.

Wenn ich jedoch eine REST-API veröffentliche, muss ich eine lesbare API-Dokumentation bereitstellen, sonst verwendet niemand meine API.

Dieser Blogbeitrag beschreibt, wie wir dieses Problem lösen können. Wir werden lernen, wie wir mithilfe von Maven HTML-Dokumentation aus RAML-Dokumenten generieren können.

Beginnen wir mit der Installation der erforderlichen Tools.

Installieren der erforderlichen Tools

Wir können RAML-Dokumente in HTML umwandeln, indem wir ein Dienstprogramm namens raml2html verwenden. Wir können es installieren, indem wir diesen Schritten folgen:

Zuerst , ist der einfachste Weg, raml2html zu installieren, die Verwendung von NPM. Mit anderen Worten, wir müssen NPM installieren, bevor wir raml2html installieren können. Wir können dies tun, indem wir den Anweisungen in der Node.js-Referenzdokumentation folgen.

Zweiter , nachdem wir Node.js installiert haben, können wir raml2html installieren. Da wir es als Kommandozeilentool verwenden wollen, müssen wir es global installieren. Wir können dies tun, indem wir den folgenden Befehl an der Eingabeaufforderung ausführen:

npm install -g raml2html

Nachdem wir raml2html installiert haben, können wir HTML aus einem einzelnen RAML-Dokument generieren, indem wir den folgenden Befehl an der Eingabeaufforderung ausführen:

raml2html -i [input file path] -o [output file path]

Wir haben jetzt alle erforderlichen Tools installiert. Fahren wir fort und konfigurieren unseren Maven-Build.

Konfigurieren unseres Maven-Builds

Unser nächster Schritt besteht darin, die raml2html-Anwendung mit Maven aufzurufen. Wir möchten die raml2html-Anwendung aufrufen, wenn wir unser Maven-Projekt packen, da es auf diese Weise keine unnötigen Verzögerungen bei der Kompilierung oder beim Komponententest verursacht.

Wir können unseren Maven-Build konfigurieren, indem wir diesen Schritten folgen:

  1. Fügen Sie das Exec Maven Plugin zu den Plugins hinzu Abschnitt unserer pom.xml Datei.
  2. Erstellen Sie eine Ausführung, die die exec des Plugins aufruft Ziel, wenn das Paket Phase des Maven-Standardlebenszyklus aufgerufen wird.
  3. Stellen Sie sicher, dass das Exec Maven Plugin raml2html ausführt Anwendung.
  4. Konfigurieren Sie den Speicherort der Eingabedatei (src/docs/api.raml ) und den Speicherort der Ausgabedatei (target/api.html ).

Der Build Abschnitt unserer pom.xml Datei sieht wie folgt aus:

<build>
	<plugins>
		<plugin>
			<groupId>org.codehaus.mojo</groupId>
			<artifactId>exec-maven-plugin</artifactId>
			<version>1.4.0</version>
			<executions>
				<execution>
					<phase>package</phase>
					<goals>
						<goal>exec</goal>
					</goals>
				</execution>
			</executions>
			<configuration>
				<executable>raml2html</executable>
				<commandlineArgs>-i src/docs/api.raml -o target/api.html</commandlineArgs>
			</configuration>
		</plugin>
	</plugins>
</build>

Wir können jetzt die HTML-API-Dokumentation erstellen, indem wir den folgenden Befehl an der Eingabeaufforderung ausführen:

mvn clean package

Dies transformiert die src/docs/api.raml Datei in HTML und schreibt das erstellte HTML in die target/api.html Datei. Die API-Dokumentation unserer Beispielanwendung sieht wie folgt aus:

Fassen wir zusammen, was wir aus diesem Blogbeitrag gelernt haben.

Zusammenfassung

Dieser Blogpost hat uns zwei Dinge gelehrt:

  • Wir können RAML-Dokumente in HTML umwandeln, indem wir raml2html verwenden.
  • Wir können raml2html während unseres Maven-Builds aufrufen, indem wir das Exec-Maven-Plugin verwenden.

P.S. Sie können die Beispielanwendung dieses Blogbeitrags von Github herunterladen.


Java-Tag