Cet article est une réimpression de ce qui a été publié sur Blog.
Je l'ai résumé du point de vue de la génération récente de spécifications d'API Java.
Orienté objet a le concept d'encapsulation, et la structure est telle que la valeur attendue est renvoyée lorsqu'une méthode de classe est appelée. Cependant, si vous ne savez pas à l'avance ce qu'il faut passer en argument, quel type de valeur sera retournée, quel type de traitement d'exception se produira en cas d'anomalie, etc., le code sera dispersé de manière ponctuelle. Ce sera. Par conséquent, il est judicieux de définir correctement l'API afin que les utilisateurs puissent utiliser des méthodes de classe sans gaspillage et en toute tranquillité d'esprit. C'est pourquoi les spécifications API sont nécessaires.
De là, expliquons la procédure de génération des spécifications API actuellement utilisées dans le projet.
Tout d'abord, JavaDoc que tout le monde connaît. Générez des spécifications d'API basées sur des commentaires au format JavaDoc. Puisque le projet utilise Maven, j'essaie de le générer à partir de la commande mvn.
Extrait partiel de 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>
La commande mvn pour générer les spécifications d'API est la suivante.
$ mvn javadoc:javadoc
Une fois le traitement terminé, les fichiers HTML seront générés dans target \ site \ apidocs. Voir la phrase suivante pour la raison pour laquelle le code source se trouve dans sourcepath.
Le projet utilise Lombok pour simplifier la description standard des beans et des DI. Étant donné que la description Lombok est convertie en code Java au moment de la compilation, il n'est pas nécessaire d'amener la bibliothèque Lombok sur le serveur d'applications à la destination de la construction. C'est un outil indispensable pour le développement Java.
Cependant, lors de la génération de spécifications avec JavaDoc, la description Lombok n'est pas soumise aux spécifications de l'API. Par conséquent, il est nécessaire de convertir temporairement la description de Lombok en code Java (cela s'appelle officiellement delombok). En spécifiant le code source complété par delombok comme emplacement du code source JavaDoc, vous pouvez générer une spécification d'API précise sans omission. Si vous le compilez avec la commande mvn, il sera automatiquement supprimé.
Extrait partiel de 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>
La commande mvn pour exécuter delombok est la suivante.
$ mvn compile
Une fois la compilation terminée, le code source delombok sera généré dans target / generate-sources / delombok.
Le traitement côté serveur par communication asynchrone est devenu un problème majeur dans les applications WEB récentes. Bien sûr, il existe de nombreux cas où une API REST est fournie, et même compte tenu de cette situation, il est souhaitable de créer une spécification d'API REST. Le projet intègre actuellement Swagger. Swaggaer a été adopté par Amazon API Gateway et Azure API Management, il est donc presque en train de devenir la norme de facto. Il est prudent d'adopter Swagger à ce stade. Générez les spécifications de l'API REST à l'aide du plug-in Swagger de Maven publié par des bénévoles.
Extrait partiel de 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>
La commande mvn pour exécuter delombok est la suivante.
$ mvn compile
Target / generated / document.html sera généré après la compilation. Veuillez obtenir les fichiers à placer dans templatePath à partir de api-doc-template / v3.0.
La technologie informatique devient très populaire et obsolète, de sorte que le contenu décrit ici peut être mis à jour après un certain temps.
Recommended Posts