परिचय

स्मार्ट-डॉक एक शक्तिशाली दस्तावेज़ निर्माण उपकरण है जो डेवलपर्स को जावा परियोजनाओं के लिए आसानी से स्पष्ट और विस्तृत एपीआई दस्तावेज़ बनाने में मदद करता है। वेबसॉकेट तकनीक की बढ़ती लोकप्रियता के साथ, स्मार्ट-डॉक ने संस्करण 3.0.7 से शुरू करके वेबसॉकेट इंटरफेस के लिए समर्थन जोड़ा है। यह आलेख विस्तार से बताएगा कि जावा वेबसॉकेट इंटरफ़ेस दस्तावेज़ तैयार करने के लिए स्मार्ट-डॉक का उपयोग कैसे करें और वेबसॉकेट सर्वर का एक पूरा उदाहरण प्रदान करें।

वेबसॉकेट प्रौद्योगिकी का अवलोकन

सबसे पहले, आइए वेबसॉकेट तकनीक को संक्षेप में समझें। वेबसॉकेट प्रोटोकॉल एक पूर्ण-डुप्लेक्स संचार चैनल प्रदान करता है, जो क्लाइंट और सर्वर के बीच डेटा विनिमय को सरल और अधिक कुशल बनाता है। जावा में, डेवलपर्स JSR 356: WebSocket के लिए Java API का उपयोग करके आसानी से WebSocket सर्वर और क्लाइंट को कार्यान्वित कर सकते हैं।

वेबसॉकेट एनोटेशन अवलोकन

जावा वेबसॉकेट में, @ServerEndpoint एनोटेशन का उपयोग POJO क्लास को वेबसॉकेट सर्वर एंडपॉइंट के रूप में परिभाषित करने के लिए किया जाता है। इस एनोटेशन से चिह्नित विधियों को वेबसॉकेट ईवेंट (जैसे कनेक्शन स्थापना, संदेश रिसेप्शन इत्यादि) होने पर स्वचालित रूप से कॉल किया जा सकता है। @ServerEndpoint के अलावा, कई अन्य WebSocket-संबंधित एनोटेशन हैं:

1. @OnOpen: यह विधि तब ट्रिगर होती है जब कोई क्लाइंट सर्वर के साथ वेबसॉकेट कनेक्शन स्थापित करता है। इसका उपयोग आमतौर पर संसाधनों को आरंभ करने या स्वागत संदेश भेजने के लिए किया जाता है।

2. @OnMessage: यह विधि तब चालू हो जाती है जब सर्वर को क्लाइंट से एक संदेश प्राप्त होता है। यह प्राप्त संदेश को संसाधित करने और संबंधित संचालन करने के लिए जिम्मेदार है।

3. @OnClose: जब क्लाइंट वेबसॉकेट कनेक्शन बंद कर देता है तो यह विधि चालू हो जाती है। इसका उपयोग आमतौर पर संसाधनों को जारी करने या सफाई कार्य करने के लिए किया जाता है।

4. @OnError: यदि वेबसॉकेट संचार के दौरान कोई त्रुटि होती है तो यह विधि चालू हो जाती है। यह त्रुटि स्थितियों को संभालता है, जैसे लॉगिंग या उपयोगकर्ता को सूचित करना।

स्मार्ट-डॉक का परिचय

स्मार्ट-डॉक जावा पर आधारित एक हल्का एपीआई दस्तावेज़ निर्माण उपकरण है। यह स्रोत कोड और टिप्पणियों से इंटरफ़ेस जानकारी निकालने का समर्थन करता है, स्वचालित रूप से मार्कडाउन प्रारूप में दस्तावेज़ तैयार करता है। वेबसॉकेट परियोजनाओं के लिए, इसका मतलब है कि आप कठिन दस्तावेज़ विवरण मैन्युअल रूप से लिखे बिना सीधे अपने सर्वरएंडपॉइंट कक्षाओं से दस्तावेज़ निकाल सकते हैं।

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

वेबसॉकेट इंटरफ़ेस दस्तावेज़ीकरण उत्पन्न करने के लिए स्मार्ट-डॉक को कॉन्फ़िगर करना

पर्यावरण तैयार करना

सुनिश्चित करें कि आपके विकास परिवेश में निम्नलिखित घटक स्थापित हैं:

• जावा 17 या उच्चतर
• बिल्ड टूल के रूप में मेवेन या ग्रैडल
• स्मार्ट-डॉक प्लगइन का नवीनतम संस्करण
• वेबसॉकेट सर्वर कार्यान्वयन लाइब्रेरी, जैसे कि javax.websocket (आमतौर पर जावा एसई में शामिल)

एक वेबसॉकेट सर्वर बनाना

प्लगइन निर्भरता जोड़ना

pom.xml फ़ाइल में स्मार्ट-डॉक निर्भरता जोड़ें:

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

एक वेबसॉकेट सर्वर एंडपॉइंट बनाना

संदेश प्रकार (संदेश) को परिभाषित करें, जो क्लाइंट से प्राप्त संदेश का प्रतिनिधित्व करने वाला एक सरल POJO है।

public class Message {
    private String content;

    // getter and setter methods
}

प्रतिक्रिया प्रकार (नमूना प्रतिक्रिया) को परिभाषित करें, एक सरल पीओजेओ जो ग्राहक को वापस भेजे जाने वाले प्रतिक्रिया संदेश का प्रतिनिधित्व करता है।

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

संदेश डिकोडर (मैसेजडिकोडर) को लागू करें, जो क्लाइंट द्वारा भेजे गए संदेश को JSON प्रारूप से संदेश ऑब्जेक्ट में परिवर्तित करने के लिए जिम्मेदार है।

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

एक सरल वेबसॉकेट सर्वर बनाने के लिए सर्वरएंडपॉइंट एनोटेशन का उपयोग करें।

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

स्मार्ट-डॉक को कॉन्फ़िगर करना

स्मार्ट-डॉक को दस्तावेज़ तैयार करने का तरीका बताने के लिए एक स्मार्ट-doc.json कॉन्फ़िगरेशन फ़ाइल बनाएं।

{
  "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 API दस्तावेज़ देखने के लिए ब्राउज़र में websocket-index.html फ़ाइल खोलें।

निष्कर्ष

स्मार्ट-डॉक के साथ जावा वेबसॉकेट इंटरफ़ेस दस्तावेज़ीकरण को स्वचालित रूप से उत्पन्न करने से न केवल मैन्युअल दस्तावेज़ीकरण लेखन समय की बचत होती है, बल्कि दस्तावेज़ीकरण की सटीकता और समय पर अपडेट भी सुनिश्चित होता है। यह सिद्ध हो चुका है कि एक अच्छी दस्तावेज़ीकरण प्रबंधन रणनीति विकास दक्षता और कोड गुणवत्ता में उल्लेखनीय सुधार कर सकती है। स्मार्ट-डॉक जैसे टूल के साथ, आप दस्तावेज़ीकरण रखरखाव के मुद्दों के बारे में चिंता किए बिना वेबसॉकेट अनुप्रयोगों के विकास पर अधिक ध्यान केंद्रित कर सकते हैं।