Введение

Smart-Doc — это мощный инструмент для создания документации, который помогает разработчикам легко создавать понятную и подробную документацию по API для проектов Java. С ростом популярности технологии WebSocket в Smart-Doc добавлена ​​поддержка интерфейсов WebSocket, начиная с версии 3.0.7. В этой статье подробно описано, как использовать Smart-Doc для создания документации по интерфейсу Java WebSocket, и представлен полный пример сервера WebSocket.

Обзор технологии WebSocket

Во-первых, давайте кратко разберемся с технологией WebSocket. Протокол WebSocket обеспечивает полнодуплексный канал связи, что делает обмен данными между клиентом и сервером более простым и эффективным. На Java разработчики могут легко реализовать серверы и клиенты WebSocket, используя JSR 356: Java API для WebSocket.

Обзор аннотаций WebSocket

В Java WebSocket аннотация @ServerEndpoint используется для определения класса POJO как конечной точки сервера WebSocket. Методы, отмеченные этой аннотацией, могут автоматически вызываться при возникновении событий WebSocket (таких как установление соединения, прием сообщения и т. д.). Помимо @ServerEndpoint, существует несколько других аннотаций, связанных с WebSocket:

1. @OnOpen: этот метод срабатывает, когда клиент устанавливает соединение WebSocket с сервером. Обычно он используется для инициализации ресурсов или отправки приветственного сообщения.

2. @OnMessage: этот метод срабатывает, когда сервер получает сообщение от клиента. Он отвечает за обработку полученного сообщения и выполнение соответствующих операций.

3. @OnClose: этот метод срабатывает, когда клиент закрывает соединение WebSocket. Обычно он используется для освобождения ресурсов или выполнения работ по очистке.

4. @OnError: этот метод срабатывает, если во время связи через WebSocket возникает ошибка. Он обрабатывает ситуации ошибок, такие как регистрация или уведомление пользователя.

Введение в Смарт-Док

Smart-Doc — это легкий инструмент для создания документации API, основанный на Java. Он поддерживает извлечение информации об интерфейсе из исходного кода и комментариев, автоматическое создание документации в формате Markdown. Для проектов WebSocket это означает, что вы можете напрямую извлекать документацию из классов ServerEndpoint без написания утомительных описаний документации вручную.

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

Настройка Smart-Doc для создания документации по интерфейсу WebSocket

Подготовка окружающей среды

Убедитесь, что в вашей среде разработки установлены следующие компоненты:

• Java 17 или выше
• Maven или Gradle в качестве инструмента сборки
• Последняя версия плагина Smart-Doc
• Библиотека реализации сервера WebSocket, например javax.websocket (обычно включенная в Java SE)

Создание сервера WebSocket

Добавление зависимости плагина

Добавьте зависимость Smart-Doc в файл pom.xml:

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

Создание конечной точки сервера WebSocket

Определите тип сообщения (Message), простой POJO, представляющий сообщение, полученное от клиента.

public class Message {
    private String content;

    // getter and setter methods
}

Определите тип ответа (SampleResponse), простой POJO, представляющий ответное сообщение, которое будет отправлено обратно клиенту.

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

Реализовать декодер сообщений (MessageDecoder), отвечающий за преобразование отправленного клиентом сообщения из формата JSON в объект 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() {
    }
}

Реализовать кодировщик ответа (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.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 в браузере, чтобы просмотреть документацию по API WebSocket.

Заключение

Автоматическое создание документации по интерфейсу Java WebSocket с помощью Smart-Doc не только экономит много времени на написание документации вручную, но также обеспечивает точность и своевременное обновление документации. Доказано, что хорошая стратегия управления документацией может значительно повысить эффективность разработки и качество кода. С помощью таких инструментов, как Smart-Doc, вы можете больше сосредоточиться на разработке приложений WebSocket, не беспокоясь о проблемах с обслуживанием документации.