Neueste Generierung von Java-API-Spezifikationen

Dieser Artikel ist ein Nachdruck dessen, was auf Blog veröffentlicht wurde.

Ich habe es unter dem Gesichtspunkt der jüngsten Generierung von Java-API-Spezifikationen zusammengefasst.

Warum ist es eine API-Spezifikation?

Objektorientiert hat das Konzept der Kapselung, und die Struktur ist so, dass der erwartete Wert zurückgegeben wird, wenn eine Klassenmethode aufgerufen wird. Wenn Sie jedoch nicht im Voraus wissen, was als Argument zu übergeben ist, welche Art von Wert zurückgegeben wird, welche Art von Ausnahmeverarbeitung im Falle einer Abnormalität usw. erfolgt, wird der Code ad hoc verteilt. Es wird sein. Daher ist es eine gute Idee, die API richtig zu definieren, damit der Benutzer die Klassenmethode ohne Verschwendung und in aller Ruhe verwenden kann. Aus diesem Grund werden API-Spezifikationen benötigt.

Verwenden von JavaDoc

Lassen Sie uns hier die Vorgehensweise zum Generieren der derzeit im Projekt verwendeten API-Spezifikationen erläutern.

Zuallererst JavaDoc, das jeder kennt. Generieren Sie API-Spezifikationen basierend auf Kommentaren im JavaDoc-Format. Da das Projekt Maven verwendet, versuche ich, es aus dem Befehl mvn zu generieren.

Teilauszug aus pom.xml

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <configuration>
                <defaultVersion>${project.version}</defaultVersion>
                <sourcepath>target/generated-sources/delombok</sourcepath>
            </configuration>
        </plugin>
    </plugins>
</build>

Der Befehl mvn zum Generieren von API-Spezifikationen lautet wie folgt.

$ mvn javadoc:javadoc

Nach Abschluss der Verarbeitung werden HTML-Dateien in "target \ site \ apidocs" generiert. Im folgenden Satz finden Sie den Grund, warum sich der Quellcode im Quellpfad befindet.

Unterstützung für Lombok

Das Projekt verwendet Lombok, um die Standardbeschreibung von Beans und DIs zu vereinfachen. Da die Lombok-Beschreibung beim Kompilieren in Java-Code konvertiert wird, muss die Lombok-Bibliothek nicht auf dem Anwendungsserver am Erstellungsziel bereitgestellt werden. Es ist ein unverzichtbares Werkzeug für die Java-Entwicklung.

Beim Generieren von Spezifikationen mit JavaDoc unterliegt die Lombok-Beschreibung jedoch nicht den API-Spezifikationen. Daher ist es notwendig, die Lombok-Beschreibung vorübergehend in Java-Code zu konvertieren (dies wird offiziell als Delombok bezeichnet). Durch Angabe des von Delombok vervollständigten Quellcodes als JavaDoc-Quellcode-Speicherort können Sie eine genaue API-Spezifikation ohne Auslassung generieren. Wenn Sie es mit dem Befehl mvn kompilieren, wird es automatisch delombok.

Teilauszug aus pom.xml

<dependencies>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>


<build>
    <plugins>
        <plugin>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok-maven-plugin</artifactId>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>delombok</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <addOutputDirectory>false</addOutputDirectory>
                <sourceDirectory>src/main/java</sourceDirectory>
            </configuration>
        </plugin>
    </plugins>
</build>

Der Befehl mvn zum Ausführen von delombok lautet wie folgt.

$ mvn compile

Nach Abschluss der Kompilierung wird der Delombok-Quellcode in "target / generate-sources / delombok" generiert.

Verwendung von Swagger

Die serverseitige Verarbeitung durch asynchrone Kommunikation ist in den letzten WEB-Anwendungen zu einem Hauptproblem geworden. Natürlich gibt es viele Fälle, in denen eine REST-API bereitgestellt wird, und selbst unter Berücksichtigung dieser Situation ist es wünschenswert, eine REST-API-Spezifikation zu erstellen. Das Projekt beinhaltet derzeit Swagger. Swaggaer wurde von Amazon API Gateway und Azure API Management übernommen und wird daher fast zum De-facto-Standard. Es ist sicher, Swagger an diesem Punkt zu adoptieren. Generieren Sie REST-API-Spezifikationen mit dem von Freiwilligen veröffentlichten Swagger-Plug-In von Maven.

Teilauszug aus pom.xml

<dependencies>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>


<build>
    <plugins>
        <plugin>
            <groupId>com.github.kongchen</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <configuration>
                <apiSources>
                    <apiSource>
                        <springmvc>false</springmvc>
                        <locations>com.shdsd.plugin.label.printer.rest</locations>
                        <info>
                            <title>${project.name} API</title>
                            <version>${project.version}</version>
                        </info>
                        <templatePath>${project.basedir}/src/test/resources/strapdown.html.hbs</templatePath>
                        <outputPath>${project.basedir}/target/generated/document.html</outputPath>
                        <swaggerDirectory>${project.basedir}/target/swagger-ui</swaggerDirectory>
                    </apiSource>
                </apiSources>
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Der Befehl mvn zum Ausführen von delombok lautet wie folgt.

$ mvn compile

Target / generate / document.html wird nach der Kompilierung generiert. Die Dateien, die in templatePath abgelegt werden sollen, erhalten Sie unter api-doc-template / v3.0.

Schließlich

Die IT-Technologie wird immer beliebter und veralteter, sodass die hier beschriebenen Inhalte möglicherweise nach einer Weile aktualisiert werden.