Introduction

Smart-Doc est un puissant outil de génération de documentation qui aide les développeurs à créer facilement une documentation API claire et détaillée pour les projets Java. Avec la popularité croissante de la technologie WebSocket, Smart-Doc a ajouté la prise en charge des interfaces WebSocket à partir de la version 3.0.7. Cet article détaillera comment utiliser Smart-Doc pour générer la documentation de l'interface Java WebSocket et fournira un exemple complet de serveur WebSocket.

Présentation de la technologie WebSocket

Tout d'abord, comprenons brièvement la technologie WebSocket. Le protocole WebSocket fournit un canal de communication full-duplex, rendant l'échange de données entre le client et le serveur plus simple et plus efficace. En Java, les développeurs peuvent facilement implémenter des serveurs et des clients WebSocket à l'aide de JSR 356 : API Java pour WebSocket.

Présentation des annotations WebSocket

Dans Java WebSocket, l'annotation @ServerEndpoint est utilisée pour définir une classe POJO en tant que point de terminaison du serveur WebSocket. Les méthodes marquées de cette annotation peuvent être automatiquement appelées lorsque des événements WebSocket (tels que l'établissement d'une connexion, la réception d'un message, etc.) se produisent. Outre @ServerEndpoint, il existe plusieurs autres annotations liées à WebSocket :

1. @OnOpen : cette méthode est déclenchée lorsqu'un client établit une connexion WebSocket avec le serveur. Il est généralement utilisé pour initialiser des ressources ou envoyer un message de bienvenue.

2. @OnMessage : Cette méthode est déclenchée lorsque le serveur reçoit un message du client. Il est chargé de traiter le message reçu et d'effectuer les opérations correspondantes.

3. @OnClose : Cette méthode est déclenchée lorsque le client ferme la connexion WebSocket. Il est généralement utilisé pour libérer des ressources ou effectuer des travaux de nettoyage.

4. @OnError : Cette méthode est déclenchée si une erreur survient lors de la communication WebSocket. Il gère les situations d'erreur, telles que la journalisation ou la notification à l'utilisateur.

Introduction à Smart-Doc

Smart-Doc est un outil léger de génération de documentation API basé sur Java. Il prend en charge l'extraction des informations d'interface à partir du code source et des commentaires, générant automatiquement la documentation au format Markdown. Pour les projets WebSocket, cela signifie que vous pouvez extraire directement la documentation de vos classes ServerEndpoint sans écrire manuellement des descriptions de documentation fastidieuses.

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

Configuration de Smart-Doc pour générer la documentation de l'interface WebSocket

Préparer l'environnement

Assurez-vous que les composants suivants sont installés dans votre environnement de développement :

• Java 17 ou supérieur
• Maven ou Gradle comme outil de construction
• Dernière version du plugin Smart-Doc
• Bibliothèque d'implémentation de serveur WebSocket, telle que javax.websocket (généralement incluse dans Java SE)

Création d'un serveur WebSocket

Ajout d'une dépendance au plugin

Ajoutez la dépendance Smart-Doc dans le fichier pom.xml :

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

Création d'un point de terminaison de serveur WebSocket

Définissez le type de message (Message), un simple POJO représentant le message reçu du client.

public class Message {
    private String content;

    // getter and setter methods
}

Définissez le type de réponse (SampleResponse), un simple POJO représentant le message de réponse à renvoyer au client.

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

Implémenter le décodeur de messages (MessageDecoder), chargé de convertir le message envoyé par le client du format JSON en un objet 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() {
    }
}

Implémentez l'encodeur de réponse (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() {
    }
}

Utilisez l'annotation ServerEndpoint pour créer un serveur 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();
    }
}

Configuration de Smart-Doc

Créez un fichier de configuration smart-doc.json pour indiquer à Smart-Doc comment générer la 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
}

Générer de la documentation

Exécutez la commande suivante dans la ligne de commande pour générer la documentation :

mvn smart-doc:websocket-html

Affichage de la documentation

Une fois la documentation générée, vous pouvez la trouver dans le répertoire src/main/resources/static/doc/websocket. Ouvrez le fichier websocket-index.html dans un navigateur pour afficher la documentation de l'API WebSocket.

Conclusion

La génération automatique de la documentation de l'interface Java WebSocket avec Smart-Doc permet non seulement d'économiser beaucoup de temps de rédaction manuelle de la documentation, mais garantit également l'exactitude et les mises à jour opportunes de la documentation. Il a été prouvé qu’une bonne stratégie de gestion de la documentation peut améliorer considérablement l’efficacité du développement et la qualité du code. Avec des outils comme Smart-Doc, vous pouvez vous concentrer davantage sur le développement d'applications WebSocket sans vous soucier des problèmes de maintenance de la documentation.