導入

Smart-Doc は、開発者が Java プロジェクト用の明確で詳細な API ドキュメントを簡単に作成できる強力なドキュメント生成ツールです。 WebSocket テクノロジの人気の高まりに伴い、Smart-Doc はバージョン 3.0.7 から WebSocket インターフェイスのサポートを追加しました。この記事では、Smart-Doc を使用して Java WebSocket インターフェイスのドキュメントを生成する方法を詳しく説明し、WebSocket サーバーの完全な例を提供します。

WebSocket テクノロジーの概要

まず、WebSocket テクノロジーについて簡単に理解しましょう。 WebSocket プロトコルは全二重通信チャネルを提供し、クライアントとサーバー間のデータ交換をよりシンプルかつ効率的にします。 Java では、開発者は JSR 356: Java API for WebSocket を使用して WebSocket サーバーとクライアントを簡単に実装できます。

WebSocket アノテーションの概要

Java WebSocket では、@ServerEndpoint アノテーションを使用して、POJO クラスを WebSocket サーバー エンドポイントとして定義します。このアノテーションが付けられたメソッドは、WebSocket イベント (接続の確立、メッセージの受信など) が発生したときに自動的に呼び出すことができます。 @ServerEndpoint 以外にも、WebSocket 関連のアノテーションがいくつかあります:

1. @OnOpen: このメソッドは、クライアントがサーバーとの WebSocket 接続を確立するとトリガーされます。通常、リソースを初期化するか、ウェルカム メッセージを送信するために使用されます。

2. @OnMessage: このメソッドは、サーバーがクライアントからメッセージを受信したときにトリガーされます。受信したメッセージを処理し、対応する操作を実行する責任があります。

3. @OnClose: このメソッドは、クライアントが WebSocket 接続を閉じるときにトリガーされます。通常、リソースを解放したり、クリーンアップ作業を実行したりするために使用されます。

4. @OnError: このメソッドは、WebSocket 通信中にエラーが発生した場合にトリガーされます。ログ記録やユーザーへの通知など、エラー状況を処理します。

Smart-Doc の概要

Smart-Doc は、Java に基づいた軽量の API ドキュメント生成ツールです。ソース コードとコメントからインターフェイス情報を抽出し、Markdown 形式でドキュメントを自動的に生成することをサポートします。 WebSocket プロジェクトの場合、これは、面倒なドキュメントの説明を手動で記述することなく、ServerEndpoint クラスからドキュメントを直接抽出できることを意味します。

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

WebSocket インターフェイスのドキュメントを生成するための Smart-Doc の構成

環境を整える

開発環境に次のコンポーネントがインストールされていることを確認してください:

• Java 17 以降
• ビルド ツールとしての Maven または Gradle
• Smart-Doc プラグインの最新バージョン
• WebSocket サーバー実装ライブラリ (javax.websocket など) (通常は Java SE に含まれます)

WebSocketサーバーの作成

プラグインの依存関係の追加

pom.xml ファイルに Smart-Doc 依存関係を追加します:

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

WebSocketサーバーエンドポイントの作成

メッセージ タイプ (メッセージ)、クライアントから受信したメッセージを表す単純な POJO を定義します。

public class Message {
    private String content;

    // getter and setter methods
}

クライアントに送り返される応答メッセージを表す単純な POJO である応答タイプ (SampleResponse) を定義します。

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

クライアントによって送信されたメッセージを JSON 形式から Message オブジェクトに変換するメッセージ デコーダー (MessageDecoder) を実装します。

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

レスポンス エンコーダ (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() {
    }
}

ServerEndpoint アノテーションを使用して、単純な WebSocket サーバーを作成します。

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

Smart-Doc の構成

smart-doc.json 構成ファイルを作成して、Smart-Doc にドキュメントの生成方法を知らせます。

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

ドキュメントの生成

コマンドラインで次のコマンドを実行してドキュメントを生成します:

mvn smart-doc:websocket-html

ドキュメントの閲覧

ドキュメントが生成されると、src/main/resources/static/doc/websocket ディレクトリにドキュメントが表示されます。ブラウザで websocket-index.html ファイルを開いて、WebSocket API ドキュメントを表示します。

結論

Smart-Doc を使用して Java WebSocket インターフェイスのドキュメントを自動生成すると、手動でドキュメントを作成する時間を大幅に節約できるだけでなく、ドキュメントの正確さとタイムリーな更新も保証されます。優れたドキュメント管理戦略により、開発効率とコードの品質が大幅に向上することが証明されています。 Smart-Doc のようなツールを使用すると、ドキュメントのメンテナンスの問題を心配することなく、WebSocket アプリケーションの開発に集中できます。