Introducción

Smart-Doc es una potente herramienta de generación de documentación que ayuda a los desarrolladores a crear fácilmente documentación API clara y detallada para proyectos Java. Con la creciente popularidad de la tecnología WebSocket, Smart-Doc ha agregado soporte para interfaces WebSocket a partir de la versión 3.0.7. Este artículo detallará cómo utilizar Smart-Doc para generar documentación de la interfaz Java WebSocket y proporcionará un ejemplo completo de un servidor WebSocket.

Descripción general de la tecnología WebSocket

Primero, comprendamos brevemente la tecnología WebSocket. El protocolo WebSocket proporciona un canal de comunicación full-duplex, lo que hace que el intercambio de datos entre el cliente y el servidor sea más sencillo y eficiente. En Java, los desarrolladores pueden implementar fácilmente servidores y clientes WebSocket utilizando JSR 356: API de Java para WebSocket.

Descripción general de las anotaciones de WebSocket

En Java WebSocket, la anotación @ServerEndpoint se utiliza para definir una clase POJO como punto final del servidor WebSocket. Los métodos marcados con esta anotación se pueden llamar automáticamente cuando ocurren eventos WebSocket (como establecimiento de conexión, recepción de mensajes, etc.). Además de @ServerEndpoint, hay varias otras anotaciones relacionadas con WebSocket:

1. @OnOpen: este método se activa cuando un cliente establece una conexión WebSocket con el servidor. Suele utilizarse para inicializar recursos o enviar un mensaje de bienvenida.

2. @OnMessage: este método se activa cuando el servidor recibe un mensaje del cliente. Se encarga de procesar el mensaje recibido y realizar las operaciones correspondientes.

3. @OnClose: este método se activa cuando el cliente cierra la conexión WebSocket. Generalmente se utiliza para liberar recursos o realizar trabajos de limpieza.

4. @OnError: este método se activa si se produce un error durante la comunicación WebSocket. Maneja situaciones de error, como iniciar sesión o notificar al usuario.

Introducción a Smart Doc

Smart-Doc es una herramienta ligera de generación de documentación API basada en Java. Admite la extracción de información de la interfaz del código fuente y los comentarios, generando automáticamente documentación en formato Markdown. Para proyectos WebSocket, esto significa que puede extraer documentación directamente de sus clases ServerEndpoint sin escribir manualmente tediosas descripciones de documentación.

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

Configuración de Smart-Doc para generar documentación de la interfaz WebSocket

Preparando el medio ambiente

Asegúrese de que su entorno de desarrollo tenga instalados los siguientes componentes:

• Java 17 o superior
• Maven o Gradle como herramienta de compilación
• Última versión del complemento Smart-Doc
• Biblioteca de implementación del servidor WebSocket, como javax.websocket (generalmente incluida en Java SE)

Creando un servidor WebSocket

Agregar dependencia de complementos

Agregue la dependencia Smart-Doc en el archivo pom.xml:

    
        com.ly.smart-doc
        smart-doc-maven-plugin
        [Latest version]
        
            
            ./src/main/resources/smart-doc.json
        
    

Crear un punto final del servidor WebSocket

Defina el tipo de mensaje (Mensaje), un POJO simple que representa el mensaje recibido del cliente.

public class Message {
    private String content;

    // getter and setter methods
}

Defina el tipo de respuesta (SampleResponse), un POJO simple que representa el mensaje de respuesta que se enviará al cliente.

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

Implementar el decodificador de mensajes (MessageDecoder), responsable de convertir el mensaje enviado por el cliente del formato JSON a un objeto Message.

public class MessageDecoder implements Decoder.Text {

    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() {
    }
}

Implementar el codificador de respuesta (MessageResponseEncoder).

public class MessageResponseEncoder implements Encoder.Text {

    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() {
    }
}

Utilice la anotación ServerEndpoint para crear un servidor WebSocket simple.

/**
 * 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();
    }
}

Configuración de Smart Doc

Cree un archivo de configuración smart-doc.json para que Smart-Doc sepa cómo generar documentación.

{
  "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
}

Generando documentación

Ejecute el siguiente comando en la línea de comando para generar documentación:

mvn smart-doc:websocket-html

Ver la documentación

Una vez generada la documentación, puede encontrarla en el directorio src/main/resources/static/doc/websocket. Abra el archivo websocket-index.html en un navegador para ver la documentación de la API de WebSocket.

Conclusión

La generación automática de documentación de la interfaz Java WebSocket con Smart-Doc no solo ahorra una gran cantidad de tiempo de redacción de documentación manual, sino que también garantiza la precisión y las actualizaciones oportunas de la documentación. Se ha demostrado que una buena estrategia de gestión de la documentación puede mejorar significativamente la eficiencia del desarrollo y la calidad del código. Con herramientas como Smart-Doc, puedes centrarte más en el desarrollo de aplicaciones WebSocket sin preocuparte por problemas de mantenimiento de la documentación.