Java >> Java tutorial >  >> Tag >> maven

Generering af HTML-dokumentation fra RAML-dokumenter med Maven

maven

RESTful API Modeling Language (RAML) er et YAML-baseret sprog, der bruges til at beskrive REST(ful) API'er.

Jeg kan godt lide RAML-syntaksen, fordi den er tekstbaseret, alsidig og nem at bruge.

Men når jeg udgiver en REST API, skal jeg levere læsbar API-dokumentation, ellers vil ingen bruge min API.

Dette blogindlæg beskriver, hvordan vi kan løse det problem. Vi vil lære, hvordan vi kan generere HTML-dokumentation fra RAML-dokumenter ved at bruge Maven.

Lad os starte med at installere de nødvendige værktøjer.

Installation af de nødvendige værktøjer

Vi kan transformere RAML-dokumenter til HTML ved at bruge et hjælpeprogram kaldet raml2html. Vi kan installere det ved at følge disse trin:

Først , den nemmeste måde at installere raml2html på er at bruge NPM. Med andre ord skal vi installere NPM, før vi kan installere raml2html. Vi kan gøre dette ved at følge instruktionerne fra Node.js-referencedokumentationen.

Anden , efter at vi har installeret Node.js, kan vi installere raml2html. Fordi vi ønsker at bruge det som et kommandolinjeværktøj, er vi nødt til at installere det globalt. Vi kan gøre dette ved at køre følgende kommando ved kommandoprompten:

npm install -g raml2html

Efter at vi har installeret raml2html, kan vi generere HTML fra et enkelt RAML-dokument ved at køre følgende kommando ved kommandoprompten:

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

Vi har nu installeret alle de nødvendige værktøjer. Lad os gå videre og konfigurere vores Maven-build.

Konfiguration af vores Maven Build

Vores næste trin er at påkalde raml2html-applikationen med Maven. Vi ønsker at påberåbe os raml2html-applikationen, når vi pakker vores Maven-projekt, fordi det på denne måde ikke forårsager unødvendige forsinkelser til kompilering eller enhedstestning.

Vi kan konfigurere vores Maven build ved at følge disse trin:

  1. Tilføj Exec Maven Plugin til plugins sektion af vores pom.xml fil.
  2. Opret en udførelse, der kalder pluginnets exec mål, når pakken fase af Mavens standardlivscyklus påkaldes.
  3. Sørg for, at Exec Maven-plugin'et udfører raml2html ansøgning.
  4. Konfigurer placeringen af ​​inputfilen (src/docs/api.raml ) og placeringen af ​​outputfilen (target/api.html ).

bygningen sektion af vores pom.xml fil ser ud som følger:

<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>

Vi kan nu oprette HTML API-dokumentationen ved at køre følgende kommando ved kommandoprompten:

mvn clean package

Dette transformerer src/docs/api.raml fil til HTML og skriver den oprettede HTML til target/api.html fil. API-dokumentationen til vores eksempelapplikation ser ud som følger:

Lad os opsummere, hvad vi lærte af dette blogindlæg.

Oversigt

Dette blogindlæg har lært os to ting:

  • Vi kan transformere RAML-dokumenter til HTML ved at bruge raml2html.
  • Vi kan påberåbe raml2html under vores Maven build ved at bruge Exec Maven Plugin.

P.S. Du kan få eksemplet på anvendelsen af ​​dette blogindlæg fra Github.


Java tag