This article is a reprint of the one posted on Blog.
I summarized it from the viewpoint of recent Java API specification generation.
Object-oriented has the concept of encapsulation, and it has a structure in which the expected value is returned when a class method is called. However, if you do not know in advance what to pass as an argument, what kind of value will be returned, what kind of exception handling will occur in the event of an abnormality, etc., the code will be scattered on an ad hoc basis. It will be. Therefore, it is a good idea to define the API properly so that the user can use the class method without waste and with peace of mind. That's why we need API specifications.
From here, let's explain the procedure for generating the API specifications currently used in the project.
The first is JavaDoc, which you all know. Generate API specifications based on comments in JavaDoc format. Since Maven is used in the project, it is generated from the mvn command.
Partial excerpt from 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>
The mvn command for generating API specifications is as follows.
$ mvn javadoc:javadoc
After the processing is completed, HTML files will be generated in target \ site \ apidocs. See the following sentence for the reason why the source code is located in sourcepath.
The project uses Lombok to simplify the standard description of beans and DIs. Since the Lombok description is converted to Java code at compile time, there is no need to bring the Lombok library to the application server at the build destination. It is an indispensable tool for Java development.
However, when generating the specification with JavaDoc, the Lombok description is not the target of the API specification. Therefore, it is necessary to temporarily convert the Lombok description to Java code (this is officially called delombok). By specifying the delombok source code as the JavaDoc source code location, you can generate an accurate API specification without omission. If you compile with the mvn command, it will automatically delombok.
Partial excerpt from 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>
The mvn command for executing delombok is as follows.
$ mvn compile
After compilation, the delombok source code will be generated in target / generate-sources / delombok.
Server-side processing by asynchronous communication has become a major issue in recent WEB applications. Of course, there are many cases where REST API is provided, and even considering this situation, it is desirable to create a REST API specification. The project is currently incorporating Swagger. Swaggaer has been adopted by Amazon API Gateway and Azure API Management, so it is becoming almost the de facto standard. It's safe to adopt Swagger at this point. Generate a REST API specification using Maven's Swagger plugin published by volunteers.
Partial excerpt from 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>
The mvn command for executing delombok is as follows.
$ mvn compile
Target / generated / document.html will be generated after compilation. Please obtain the files to be placed in templatePath from api-doc-template / v3.0.
As IT technology is so popular and obsolete, the content described here may be updated after a while.
Recommended Posts