Cara Menjana Dokumentasi API WebSocket Java Menggunakan Smart-Doc

pengenalan

Smart-Doc ialah alat penjanaan dokumentasi yang berkuasa yang membantu pembangun dengan mudah membuat dokumentasi API yang jelas dan terperinci untuk projek Java. Dengan peningkatan populariti teknologi WebSocket, Smart-Doc telah menambah sokongan untuk antara muka WebSocket bermula dari versi 3.0.7. Artikel ini akan memperincikan cara menggunakan Smart-Doc untuk menjana dokumentasi antara muka WebSocket Java dan memberikan contoh lengkap pelayan WebSocket.

Gambaran Keseluruhan Teknologi WebSocket

Pertama, mari kita fahami secara ringkas teknologi WebSocket. Protokol WebSocket menyediakan saluran komunikasi dupleks penuh, menjadikan pertukaran data antara pelanggan dan pelayan lebih mudah dan lebih cekap. Di Java, pembangun boleh melaksanakan pelayan dan pelanggan WebSocket dengan mudah menggunakan JSR 356: Java API untuk WebSocket.

Gambaran Keseluruhan Anotasi WebSocket

Dalam Java WebSocket, anotasi @ServerEndpoint digunakan untuk mentakrifkan kelas POJO sebagai titik akhir pelayan WebSocket. Kaedah yang ditandakan dengan anotasi ini boleh dipanggil secara automatik apabila peristiwa WebSocket (seperti penetapan sambungan, penerimaan mesej, dll.) berlaku. Selain @ServerEndpoint, terdapat beberapa anotasi berkaitan WebSocket lain:

1. @OnOpen: Kaedah ini dicetuskan apabila pelanggan mewujudkan sambungan WebSocket dengan pelayan. Ia biasanya digunakan untuk memulakan sumber atau menghantar mesej alu-aluan.

2. @OnMessage: Kaedah ini dicetuskan apabila pelayan menerima mesej daripada klien. Ia bertanggungjawab untuk memproses mesej yang diterima dan melaksanakan operasi yang sepadan.

3. @OnClose: Kaedah ini dicetuskan apabila pelanggan menutup sambungan WebSocket. Ia biasanya digunakan untuk mengeluarkan sumber atau melakukan kerja pembersihan.

4. @OnError: Kaedah ini dicetuskan jika ralat berlaku semasa komunikasi WebSocket. Ia mengendalikan situasi ralat, seperti mengelog atau memberitahu pengguna.

Pengenalan kepada Smart-Doc

Smart-Doc ialah alat penjanaan dokumentasi API ringan berdasarkan Java. Ia menyokong mengekstrak maklumat antara muka daripada kod sumber dan komen, menjana dokumentasi secara automatik dalam format Markdown. Untuk projek WebSocket, ini bermakna anda boleh mengekstrak terus dokumentasi daripada kelas ServerEndpoint anda tanpa menulis huraian dokumentasi yang membosankan secara manual.

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

Mengkonfigurasi Smart-Doc untuk Menjana Dokumentasi Antara Muka WebSocket

Menyediakan Alam Sekitar

Pastikan persekitaran pembangunan anda mempunyai komponen berikut dipasang:

• Java 17 atau lebih tinggi
• Maven atau Gradle sebagai alat binaan
• Versi terkini pemalam Smart-Doc
• Pustaka pelaksanaan pelayan WebSocket, seperti javax.websocket (biasanya disertakan dalam Java SE)

Mencipta Pelayan WebSocket

Menambah Ketergantungan Pemalam

Tambahkan pergantungan Smart-Doc dalam fail pom.xml:

<plugins>
    <plugin>
        <groupId>com.ly.smart-doc</groupId>
        <artifactId>smart-doc-maven-plugin</artifactId>
        <version>[Latest version]</version>
        <configuration>
            <!--smart-doc-->
            <configFile>./src/main/resources/smart-doc.json</configFile>
        </configuration>
    </plugin>
</plugins>

Mencipta Titik Akhir Pelayan WebSocket

Tentukan jenis mesej (Mesej), POJO ringkas yang mewakili mesej yang diterima daripada pelanggan.

public class Message {
    private String content;

    // getter and setter methods
}

Tentukan jenis respons (SampleResponse), POJO ringkas yang mewakili mesej respons untuk dihantar semula kepada pelanggan.

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

Laksanakan penyahkod mesej (MessageDecoder), bertanggungjawab untuk menukar mesej yang dihantar oleh klien daripada format JSON kepada objek Mesej.

public class MessageDecoder implements Decoder.Text<Message> {

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

Laksanakan pengekod respons (MessageResponseEncoder).

public class MessageResponseEncoder implements Encoder.Text<SampleResponse> {

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

Gunakan anotasi ServerEndpoint untuk mencipta pelayan WebSocket yang mudah.

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

Mengkonfigurasi Smart-Doc

Buat fail konfigurasi smart-doc.json untuk membolehkan Smart-Doc mengetahui cara menjana dokumentasi.

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

Menjana Dokumentasi

Jalankan arahan berikut dalam baris arahan untuk menjana dokumentasi:

mvn smart-doc:websocket-html

Melihat Dokumentasi

Selepas dokumentasi dijana, anda boleh menemuinya dalam direktori src/main/resources/static/doc/websocket. Buka fail websocket-index.html dalam penyemak imbas untuk melihat dokumentasi API WebSocket.

Kesimpulan

Menjana dokumentasi antara muka Java WebSocket secara automatik dengan Smart-Doc bukan sahaja menjimatkan banyak masa penulisan dokumentasi manual tetapi juga memastikan ketepatan dan kemas kini dokumentasi yang tepat pada masanya. Telah terbukti bahawa strategi pengurusan dokumentasi yang baik boleh meningkatkan kecekapan pembangunan dan kualiti kod dengan ketara. Dengan alatan seperti Smart-Doc, anda boleh menumpukan lebih pada pembangunan aplikasi WebSocket tanpa perlu risau tentang isu penyelenggaraan dokumentasi.

Atas ialah kandungan terperinci Cara Menjana Dokumentasi API WebSocket Java Menggunakan Smart-Doc. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!