DEV Community: Yu Sun

How to Generate Java WebSocket API Documentation Using Smart-Doc

Yu Sun — Tue, 27 Aug 2024 08:13:19 +0000

Introduction

Smart-Doc is a powerful documentation generation tool that helps developers easily create clear and detailed API documentation for Java projects. With the growing popularity of WebSocket technology, Smart-Doc has added support for WebSocket interfaces starting from version 3.0.7. This article will detail how to use Smart-Doc to generate Java WebSocket interface documentation and provide a complete example of a WebSocket server.

Overview of WebSocket Technology

First, let's briefly understand WebSocket technology. The WebSocket protocol provides a full-duplex communication channel, making data exchange between the client and server simpler and more efficient. In Java, developers can easily implement WebSocket servers and clients using JSR 356: Java API for WebSocket.

WebSocket Annotations Overview

In Java WebSocket, the @ServerEndpoint annotation is used to define a POJO class as a WebSocket server endpoint. Methods marked with this annotation can be automatically called when WebSocket events (such as connection establishment, message reception, etc.) occur. Besides @ServerEndpoint, there are several other WebSocket-related annotations:

@OnOpen: This method is triggered when a client establishes a WebSocket connection with the server. It is usually used to initialize resources or send a welcome message.
@OnMessage: This method is triggered when the server receives a message from the client. It is responsible for processing the received message and performing the corresponding operations.
@OnClose: This method is triggered when the client closes the WebSocket connection. It is usually used to release resources or perform cleanup work.
@OnError: This method is triggered if an error occurs during WebSocket communication. It handles error situations, such as logging or notifying the user.

Introduction to Smart-Doc

Smart-Doc is a lightweight API documentation generation tool based on Java. It supports extracting interface information from source code and comments, automatically generating documentation in Markdown format. For WebSocket projects, this means you can directly extract documentation from your ServerEndpoint classes without manually writing tedious documentation descriptions.

https://github.com/TongchengOpenSource/smart-doc

Configuring Smart-Doc to Generate WebSocket Interface Documentation

Preparing the Environment

Ensure your development environment has the following components installed:

Java 17 or higher
Maven or Gradle as the build tool
Latest version of Smart-Doc plugin
WebSocket server implementation library, such as javax.websocket (usually included in Java SE)

Creating a WebSocket Server

Adding Plugin Dependency

Add the Smart-Doc dependency in the pom.xml file:



<plugins>
    <plugin>
        <groupId>com.ly.smart-doc</groupId>
        <artifactId>smart-doc-maven-plugin</artifactId>
        <version>[Latest version]</version>
        <configuration>
            <!--smart-doc-->
            <configFile>./src/main/resources/smart-doc.json</configFile>
        </configuration>
    </plugin>
</plugins>

Creating a WebSocket Server Endpoint

Define the message type (Message), a simple POJO representing the message received from the client.



public class Message {
    private String content;

    // getter and setter methods
}

Define the response type (SampleResponse), a simple POJO representing the response message to be sent back to the client.



public class SampleResponse {
    private String responseContent;
    // getter and setter methods
}

Implement the message decoder (MessageDecoder), responsible for converting the message sent by the client from JSON format to a Message object.



public class MessageDecoder implements Decoder.Text<Message> {

    private static final ObjectMapper objectMapper = new ObjectMapper();
    @Override
    public Message decode(String s) throws DecodeException {
        try {
            return objectMapper.readValue(s, Message.class);
        } catch (Exception e) {
            throw new DecodeException(s, "Unable to decode text to Message", e);
        }
    }
    @Override
    public boolean willDecode(String s) {
        return (s != null);
    }

    @Override
    public void init(EndpointConfig endpointConfig) {
    }
    @Override
    public void destroy() {
    }
}

Implement the response encoder (MessageResponseEncoder).



public class MessageResponseEncoder implements Encoder.Text<SampleResponse> {

    private static final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public String encode(SampleResponse response) {
        try {
            return objectMapper.writeValueAsString(response);
        } catch (Exception e) {
            throw new RuntimeException("Unable to encode SampleResponse", e);
        }
    }

    @Override
    public void init(EndpointConfig endpointConfig) {
    }

    @Override
    public void destroy() {
    }
}

Use the ServerEndpoint annotation to create a simple WebSocket server.



/**



WebSocket server endpoint example.

*/

@Component

@ServerEndpoint(value = "/ws/chat/{userId}",

    decoders = {MessageDecoder.class},

    encoders = {MessageResponseEncoder.class})

public class ChatEndpoint {

/**


Called when a new connection is established.
*
@param session the client session
@param userId  the user ID
*/
@OnOpen
public void onOpen(Session session, @PathParam("userId") String userId) {
System.out.println("Connected: " + session.getId() + ", User ID: " + userId);
}



/**


Called when a message is received from the client.
*
@param message the message sent by the client
@param session the client session
@return the response message
*/
@OnMessage
public SampleResponse receiveMessage(Message message, Session session) {
System.out.println("Received message: " + message);
return new SampleResponse(message.getContent());
}



/**


Called when the connection is closed.
*
@param session the client session
*/
@OnClose
public void onClose(Session session) {
System.out.println("Disconnected: " + session.getId());
}



/**


Called when an error occurs.
*
@param session   the client session
@param throwable the error
*/
@OnError
public void onError(Session session, Throwable throwable) {
throwable.printStackTrace();
}
}

Configuring Smart-Doc

Create a smart-doc.json configuration file to let Smart-Doc know how to generate documentation.



{

  "serverUrl": "http://smart-doc-demo:8080", // Set the server address, not required

  "outPath": "src/main/resources/static/doc" // Specify the output path of the document

}

Generating Documentation

Run the following command in the command line to generate documentation:



mvn smart-doc:websocket-html

Viewing the Documentation

After the documentation is generated, you can find it in the src/main/resources/static/doc/websocket directory. Open the websocket-index.html file in a browser to view the WebSocket API documentation.

Conclusion

Automatically generating Java WebSocket interface documentation with Smart-Doc not only saves a lot of manual documentation writing time but also ensures the accuracy and timely updates of the documentation. It has been proven that a good documentation management strategy can significantly improve development efficiency and code quality. With tools like Smart-Doc, you can focus more on the development of WebSocket applications without worrying about documentation maintenance issues.

Documenting a Spring REST API Using Smart-doc

Yu Sun — Sat, 22 Jun 2024 16:10:19 +0000

If you are developing a RESTful API with Spring Boot, you want to make it as easy as possible for other developers to understand and use your API. Documentation is essential because it provides a reference for future updates and helps other developers integrate with your API. For a long time, the way to document REST APIs was to use Swagger, an open-source software framework that enables developers to design, build, document, and consume RESTful Web services. In 2018, to address the issues of code invasiveness and dependency associated with traditional API documentation tools like Swagger, we developed smart-doc and open-sourced it to the community.
In this article, we will explore how to use Smart-doc to generate documentation for a Spring Boot REST API.

What is Smart-doc?

Smart-doc is an interface documentation generation tool for Java projects. It primarily analyzes and extracts comments from Java source code to produce API documentation. Smart-doc scans standard Java comments in the code, eliminating the need for specialized annotations like those used in Swagger, thus maintaining the simplicity and non-invasiveness of the code. It supports multiple formats for document output, including Markdown, HTML5, Postman Collection, OpenAPI 3.0, etc. This flexibility allows developers to choose the appropriate documentation format based on their needs. Additionally, Smart-doc can scan code to generate JMeter performance testing scripts.

For more features, please refer to the official documentation

Steps to use Smart-doc for documenting APIs

Step 1: Maven Project

Create a Maven project with the latest version of Spring Boot
Add the Web dependencies to the project

Step 2: Add Smart-doc Into the Project

Add smart-doc-maven-plugin to the project's pom.xml



<plugin>
     <groupId>com.ly.smart-doc</groupId>
     <artifactId>smart-doc-maven-plugin</artifactId>
     <version>[latest version]</version>
     <configuration>
         <configFile>./src/main/resources/smart-doc.json</configFile>
         <projectName>${project.description}</projectName>
     </configuration>
</plugin>

Create the smart-doc.json file in the resources directory of the module where the project startup class is located. ```json

{
"outPath": "/path/to/userdir"
}


**Step 3: Create a Rest Controller**

Now let's create a controller class that will handle HTTP requests and return responses.

- Create a controller class that will be sent as a JSON response.

```java


public class User {

    /**
     * user id
     * 
     */
    private long id;

    /**
     * first name
     */
    private String firstName;

    /**
     * last name
     */
    private String lastName;

    /**
     * email address
     */
    private String email;


    public long getId() {
        return id;
    }

    public void setId(long id) {
        this.id = id;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

Now create a service class



@Repository
public class UserRepository {

    private static final Map<Long, User> users = new ConcurrentHashMap<>();

    static {
        User user = new User();
        user.setId(1);
        user.setEmail("123@gmail.com");
        user.setFirstName("Tom");
        user.setLastName("King");
        users.put(1L,user);
    }

    public Optional<User> findById(long id) {
        return Optional.ofNullable(users.get(id));
    }

    public void add(User book) {
        users.put(book.getId(), book);
    }

    public List<User> getUsers() {
        return users.values().stream().collect(Collectors.toList());
    }

    public boolean delete(User user) {
        return users.remove(user.getId(),user);
    }
}

Create the RestController Class.



/**
 * The type User controller.
 *
 * @author yu 2020/12/27.
 */
@RestController
@RequestMapping("/api/v1")
public class UserController {

    @Resource
    private UserRepository userRepository;

    /**
     * Create user.
     *
     * @param user the user
     * @return the user
     */
    @PostMapping("/users")
    public ResponseResult<User> createUser(@Valid @RequestBody User user) {
        userRepository.add(user);
        return ResponseResult.ok(user);
    }

    /**
     * Get all users list.
     *
     * @return the list
     */
    @GetMapping("/users")
    public ResponseResult<List<User>> getAllUsers() {
        return ResponseResult.ok().setResultData(userRepository.getUsers());
    }

    /**
     * Gets users by id.
     *
     * @param userId the user id|1
     * @return the users by id
     */
    @GetMapping("/users/{id}")
    public ResponseResult<User> getUsersById(@PathVariable(value = "id") Long userId) {
        User user = userRepository.findById(userId).
                orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
        return ResponseResult.ok().setResultData(user);
    }


    /**
     * Update user response entity.
     *
     * @param userId      the user id|1
     * @param userDetails the user details
     * @return the response entity
     */
    @PutMapping("/users/{id}")
    public ResponseResult<User> updateUser(@PathVariable(value = "id") Long userId, @Valid @RequestBody User userDetails) {
        User user = userRepository.findById(userId).
                orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
        user.setEmail(userDetails.getEmail());
        user.setLastName(userDetails.getLastName());
        user.setFirstName(userDetails.getFirstName());
        userRepository.add(user);
        return ResponseResult.ok().setResultData(user);
    }

    /**
     * Delete user.
     *
     * @param userId the user id|1
     * @return the map
     */
    @DeleteMapping("/user/{id}")
    public ResponseResult<Boolean> deleteUser(@PathVariable(value = "id") Long userId) {
        User user = userRepository.findById(userId).
                orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
        return ResponseResult.ok().setResultData(userRepository.delete(user));
    }
}

Step 4: Generate document

You can use the Smart-doc plugin in IntelliJ IDEA to generate the desired documentation, such as OpenAPI, Markdown, etc.

Of course, you can also use the Maven command to generate:



mvn smart-doc:html
//  Generate document output to Markdown
mvn smart-doc:markdown
// Generate document output to Adoc
mvn smart-doc:adoc
// Generate Postman.
mvn smart-doc:postman
// Generate OpenAPI 3.0+
mvn smart-doc:openapi

Step 4: Import to Postman

Here we use Smart-doc to generate a Postman.json, then import it into Postman to see the effect.

Since smart-doc supports generating documentation in multiple formats, you can choose to generate OpenAPI and then display it using Swagger UI or import it into some professional API documentation systems.

Conclusion

From the previous examples, it can be seen that Smart-doc generates documentation by scanning standard Java comments in the code, without the need for specialized annotations like Swagger, thus maintaining the simplicity and non-invasiveness of the code, and also not affecting the size of the service Jar package. It supports multiple formats for document output, including Markdown, HTML5, Postman Collection,OpenAPI 3.0, etc. This flexibility allows developers to choose the appropriate document format for output based on their needs. The Maven or Gradle plugins provided by smart-doc also facilitate users in integrating document generation in Devops pipelines.

Currently, Swagger also has its advantages, such as more powerful UI features, and better support for Springboot Webflux.

How to use smart-doc to generate JMeter test scripts

Yu Sun — Fri, 21 Jun 2024 16:14:54 +0000

smart-doc is a tool for automatically generating Java API documentation. It creates documentation by analyzing interfaces and comments in the source code, and supports a variety of document output formats, including Markdown, HTML5, OpenAPI 3.0, and more. The design goal of smart-doc is to simplify the document writing process, improve development efficiency, and ensure the accuracy and timeliness of the documentation.
In the software development lifecycle, the automatic generation of API documentation and the performance testing of interfaces are key steps in improving development efficiency and ensuring product quality. With the addition of the ability to generate JMeter performance testing scripts in smart-doc version 3.0.1, developers can more conveniently accomplish these two tasks. This article will introduce how to use smart-doc and JMeter for effective performance testing.

Generate JMeter scripts

Using Smart-doc to generate JMeter performance test scripts can significantly reduce the time taken to write performance test scripts, thereby improving testing efficiency. The JMeter scripts automatically generated by Smart-doc can be directly run in JMeter without the need for complex configuration and debugging, making performance testing much simpler and faster.

First, ensure that the smart-doc-maven-plugin has been added to your project. Then, configure the relevant parameters of the smart-doc plugin in the pom.xml file of the project, for example:

<plugin>
     <groupId>com.ly.smart-doc</groupId>
     <artifactId>smart-doc-maven-plugin</artifactId>
     <version>[latest version]</version>
     <configuration>
         <configFile>./src/main/resources/smart-doc.json</configFile>
         <projectName>${project.description}</projectName>
     </configuration>
</plugin>

Run the command mvn smart-doc:jmeter. Smart-doc will scan the project source code, extract annotation information, and automatically generate the corresponding JMeter performance test scripts.

Those who are not familiar with how to use it can refer to the official smart-doc documentation

Import Into JMeter

Open JMeter, click "File" -> "Open", select the JMeter script file generated in the first step, and click the "Start" button. JMeter will then begin performing performance tests according to the script.

Configure Prometheus

Prometheus is an open-source monitoring and alerting tool for handling time-series data. We can use it to perform real-time monitoring during the JMeter stress testing process, thereby enhancing the observability of performance testing.

Step 1: Install the JMeter Prometheus Plugin

First, you need to install the Prometheus plugin in the lib/ext directory of JMeter. You can download the plugin from the JMeter Plugins Manager or the official website . It can also be downloaded from GitHub . For this instance, download the latest version 0.7.1 from GitHub.

Note: JMeter's default listening IP address is 127.0.0.1, which by default will prevent Prometheus from connecting to the JMeter Prometheus listening port. Therefore, it is necessary to add prometheus.ip=0.0.0.0 in jmeter.properties.

Step 2: Add Prometheus Listener

Open JMeter and add the Prometheus Listener to your test plan. This can be done by right-clicking on Test Plan-> Add -> Listener -> Prometheus Listener.

The configuration of the listener can refer to the official settings, with reference as follows (smart-doc 3.0.4 supports configuring and adding Prometheus Listener generation):

Step 3: Configure Prometheus Scrape

In the configuration file of Prometheus (prometheus.yml), add a new scrape_config to fetch data from the JMeter Prometheus plugin. For example:

scrape_configs:
  - job_name: 'jmeter'
    scrape_interval: 15s
    static_configs:
        - targets: ['<Your JMeter machine IP>:9270']

Here, <Your JMeter machine IP> is the IP address of the machine running the JMeter test, and 9270 is the default listening port for the JMeter Prometheus plugin.

Step 4: Run the Test Plan

For the purpose of easy verification in this article, the thread group is set to "infinite loop" during stress testing, which can be adjusted according to actual needs.

After starting successfully, JMeter Prometheus will, by default, create a service on the local port 9270.

Access the URL http://localhost:9270/metrics and if you see the following content, it means it has been successful.

Step 5: Start Prometheus

After starting Prometheus, it will begin to fetch data from the JMeter Prometheus plugin. As shown in the following configuration, once successfully started, you can see the set targets in Prometheus.

Step 6: Configure Grafana

On the Grafana official website, find the prometheus-jmeter monitoring panel provided by the official site. Here, we select the template with ID 14927 to import into Grafana.

After clicking Load, select the Prometheus data source.

Note: During testing, it was found that the original template 14927 had some errors. These were fixed during the writing process of this article. Import the corrected template downloaded from GitHub.

After the template is successfully imported, we will be able to see the entire performance testing monitoring data in Grafana.

To facilitate a rapid experience of the entire performance testing process, the smart-doc community has curated and provided a template that can be launched with a single command using docker-compose. For those who wish to experience it through Kubernetes deployment, AI tools can be utilized to directly convert the docker-compose template into a Kubernetes deployment template.

The project for the experience also includes usage instructions.

The example code for this article can be found here.

The Assistance of Smart-Doc in JMeter Performance Testing

The combination of smart-doc and JMeter for performance stress testing offers several advantages:

Automation: smart-doc can automatically extract API information from the source code and generate JMeter performance test scripts without the need for manual writing, greatly improving efficiency.
Precision: The JMeter performance test scripts generated by smart-doc are completely consistent with the API definitions in the source code, avoiding errors that may occur when manually writing scripts.
Flexibility: smart-doc supports a variety of configuration options, allowing the generated JMeter scripts to be customized according to testing requirements.
smart-doc will also continue to improve and optimize support for JMeter. Please stay tuned for the ongoing development of the smart-doc open-source project.

Conclusion

By combining smart-doc and JMeter, we can not only automate the generation of API documentation but also swiftly create performance test scripts and conduct stress testing. This automation tool significantly enhances development and testing efficiency while helping teams more easily maintain and optimize the performance of software systems. We hope this article has provided practical references for you to apply these tools more efficiently in your daily work.

We also welcome everyone to continue to follow and support the smart-doc open-source community. In the future, we are exploring support for additional languages to assist more developers.