Introdução

Smart-Doc é uma poderosa ferramenta de geração de documentação que ajuda os desenvolvedores a criar facilmente documentação de API clara e detalhada para projetos Java. Com a crescente popularidade da tecnologia WebSocket, o Smart-Doc adicionou suporte para interfaces WebSocket a partir da versão 3.0.7. Este artigo detalhará como usar o Smart-Doc para gerar documentação da interface Java WebSocket e fornecerá um exemplo completo de um servidor WebSocket.

Visão geral da tecnologia WebSocket

Primeiro, vamos entender brevemente a tecnologia WebSocket. O protocolo WebSocket fornece um canal de comunicação full-duplex, tornando a troca de dados entre cliente e servidor mais simples e eficiente. Em Java, os desenvolvedores podem implementar facilmente servidores e clientes WebSocket usando JSR 356: Java API para WebSocket.

Visão geral das anotações WebSocket

Em Java WebSocket, a anotação @ServerEndpoint é usada para definir uma classe POJO como um endpoint do servidor WebSocket. Os métodos marcados com esta anotação podem ser chamados automaticamente quando ocorrem eventos WebSocket (como estabelecimento de conexão, recepção de mensagens, etc.). Além de @ServerEndpoint, existem várias outras anotações relacionadas ao WebSocket:

1. @OnOpen: Este método é acionado quando um cliente estabelece uma conexão WebSocket com o servidor. Geralmente é usado para inicializar recursos ou enviar uma mensagem de boas-vindas.

2. @OnMessage: Este método é acionado quando o servidor recebe uma mensagem do cliente. É responsável por processar a mensagem recebida e realizar as operações correspondentes.

3. @OnClose: Este método é acionado quando o cliente fecha a conexão WebSocket. Geralmente é usado para liberar recursos ou realizar trabalhos de limpeza.

4. @OnError: Este método é acionado se ocorrer um erro durante a comunicação WebSocket. Ele lida com situações de erro, como registrar ou notificar o usuário.

Introdução ao Smart-Doc

Smart-Doc é uma ferramenta leve de geração de documentação de API baseada em Java. Suporta a extração de informações da interface do código-fonte e comentários, gerando automaticamente documentação no formato Markdown. Para projetos WebSocket, isso significa que você pode extrair diretamente a documentação de suas classes ServerEndpoint sem escrever manualmente descrições tediosas de documentação.

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

Configurando o Smart-Doc para gerar documentação da interface WebSocket

Preparando o Meio Ambiente

Certifique-se de que seu ambiente de desenvolvimento tenha os seguintes componentes instalados:

• Java 17 ou superior
• Maven ou Gradle como ferramenta de construção
• Versão mais recente do plug-in Smart-Doc
• Biblioteca de implementação de servidor WebSocket, como javax.websocket (geralmente incluída no Java SE)

Criando um servidor WebSocket

Adicionando Dependência de Plugin

Adicione a dependência do Smart-Doc no arquivo pom.xml:

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

Criando um endpoint de servidor WebSocket

Defina o tipo de mensagem (Message), um POJO simples representando a mensagem recebida do cliente.

public class Message {
    private String content;

    // getter and setter methods
}

Defina o tipo de resposta (SampleResponse), um POJO simples representando a mensagem de resposta a ser enviada de volta ao cliente.

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

Implementar o decodificador de mensagens (MessageDecoder), responsável por converter a mensagem enviada pelo cliente do formato JSON para um 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() {
    }
}

Implemente o codificador de resposta (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() {
    }
}

Use a anotação ServerEndpoint para criar um servidor WebSocket simples.

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

Configurando o Smart-Doc

Crie um arquivo de configuração smart-doc.json para que o Smart-Doc saiba como gerar documentação.

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

Gerando Documentação

Execute o seguinte comando na linha de comando para gerar a documentação:

mvn smart-doc:websocket-html

Visualizando a Documentação

Depois que a documentação for gerada, você poderá encontrá-la no diretório src/main/resources/static/doc/websocket. Abra o arquivo websocket-index.html em um navegador para visualizar a documentação da API WebSocket.

Conclusão

A geração automática de documentação da interface Java WebSocket com Smart-Doc não apenas economiza muito tempo de escrita de documentação manual, mas também garante a precisão e atualizações oportunas da documentação. Está provado que uma boa estratégia de gerenciamento de documentação pode melhorar significativamente a eficiência do desenvolvimento e a qualidade do código. Com ferramentas como o Smart-Doc, você pode se concentrar mais no desenvolvimento de aplicações WebSocket sem se preocupar com problemas de manutenção de documentação.