Optimizing the documentation of socket interface protocols.

[shalousun]

Here is the translated template design for the WebSocket interface based on the provided Java code example:

Template Design

Before designing the template, let's review a WebSocket example:

/**
 * WebSocket ServerEndpoint with URL Path Variable
 * 
 * @author linwumingshi
 */
@ServerEndpoint(value = "/smart-doc/websocket/path/{id}")
public class WebSocketServerEndpointHasUrlPathVariable {

    /**
     * URL Path Variable id
     */
    private String id;

    /**
     * Session
     */
    private Session session;

    /**
     * OnMessage method.
     * 
     * @param message the message received from the client.
     * 
     * This method is called when a message is received and it prints the message to the console.
     */
    @OnMessage
    public void onMessage(MyMessage message) {
        System.out.println("Message from client: " + message);
    }

    /**
     * OnOpen method
     *
     * @param id      URL Path Variable id
     * @param session session
     */
    @OnOpen
    public void webSocketServerEndpointOnOpen(@PathParam(value = "id") String id, Session session) {
        this.id = id;
        this.session = session;
    }
}

Based on the above WebSocket interface, we should generate an interface template as follows:

WebSocket ServerEndpoint with URL Path Variable

URI: ws://127.0.0.1:8080/smart-doc/websocket/path/{id}

Author: linwumingshi

Description: WebSocket ServerEndpoint with URL Path Variable

SubProtocols: N/A

Path Parameters:

Parameter	Type	Required	Description	Since
id	string	true	URL Path Variable id	-

Message Parameters:

Parameter	Type	Required	Description	Since
from	string	true	Sender identifier	-
to	string	true	Recipient identifier	-
content	string	true	Message content	-

Message Body:

{
  "from": "Jordan",
  "to": "Kimi",
  "content": "Hello"
}

• If the OnMessage method is implemented, then the documentation should include Message Parameters and Message Body, similar to parsing for @RequestBody.

[shalousun]

#850

[linwumingshi]

/**
 * WebSocket ServerEndpoint with URL Path Variable
 * 
 * @author linwumingshi
 */
@ServerEndpoint(value = "/smart-doc/websocket/path/{id}",
        subprotocols = {"smart-doc", "test2"},
        decoders = {CarDecoder.class},
        encoders = {ObjectEncoder.class, CatEncoder.class})
public class WebSocketServerEndpointHasUrlPathVariable {

    /**
     * URL Path Variable id
     */
    private String id;

    /**
     * Session
     */
    private Session session;

    /**
     * OnMessage method.
     * 
     * @param message the message received from the client.
     * 
     * This method is called when a message is received and it prints the message to the console.
     */
    @OnMessage
    public void onMessage(MyMessage message) {
        System.out.println("Message from client: " + message);
       // send Message
        this.sendMessage(CommonResult.ok().addData(car));
        this.sendMessage(car);
    }

    /**
     * OnOpen method
     *
     * @param id      URL Path Variable id
     * @param session session
     */
    @OnOpen
    public void webSocketServerEndpointOnOpen(@PathParam(value = "id") String id, Session session) {
        this.id = id;
        this.session = session;
    }


    public void sendMessage(Car car) throws Exception {
        if (this.session.isOpen()) {
            this.session.getBasicRemote().sendObject(car);
        }
    }

    public void sendMessage(CommonResult<?> object) throws Exception {
        if (this.session.isOpen()) {
            this.session.getBasicRemote().sendObject(object);
        }
    }
}

---

Encoder

public class ObjectEncoder implements Encoder.Text<CommonResult<?>> {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public String encode(CommonResult<?> object) throws EncodeException {
        try {
            return objectMapper.writeValueAsString(object);
        } catch (JsonProcessingException e) {
            throw new RuntimeException(e);
        }
    }
}

public class CatEncoder implements Encoder.Text<Car> {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public String encode(Car object) throws EncodeException {
        try {
            return objectMapper.writeValueAsString(object);
        } catch (JsonProcessingException e) {
            throw new RuntimeException(e);
        }
    }
}

When the @ServerEndpoint annotation includes the encoders parameter, corresponding Encoder.Text<T> implementations should be generated for each generic parameter type. If there are multiple encoders specified, multiple corresponding parameter types should be generated

Like this

Response-parameters:

Parameter	Type	Description	Since
success	boolean	Is successful	-
message	string	Error message (while success is true return succeed)	-
data	object	Return data	-
code	string	Error code	-
timestamp	string	Response time	-
traceId	string	Trace ID	-

Parameter	Type	Description	Since
name	string	车名称	-
length	double	长度	-
pager	object	分页	-
└─concurrentPage	int32	当前页	-
└─pageSize	int32	当前page	-
└─total	int32	记录总数	-