feat: ✨ Added support for message and response parameters in WebSocket documentation

This commit significantly enhances the functionality of the WebSocket documentation generator by introducing support for message parameters and response parameters, enabling the generated documentation to more accurately reflect the details of WebSocket interfaces. The changes include, but are not limited to, the following:

1. Introduced handling of the `@OnMessage` annotation, allowing documentation to include message parameters.
2. Added extraction and display of response parameters, enabling the documentation to show the return structure of the interface.
3. Updated the documentation template to support the newly introduced features.
4. Optimized the extraction logic for WebSocket path parameters, making the parameter list in the documentation more accurate.

These changes significantly improve the utility and flexibility of the documentation generator, making the generated content more comprehensive and helping users better understand and use WebSocket interfaces.

Author: linwumingshi

README.md

@@ -15,7 +15,7 @@ based on interface source code analysis to generate interface documents, and zer
 write Javadoc comments when developing, `smart-doc` can help you generate `Markdown` or `HTML5` document. `smart-doc` does not
 need to inject annotations into the code like `Swagger`.
 
-[quick start](https://smart-doc-group.github.io/)
+**[Quick Start](https://smart-doc-group.github.io/)**
 
 ## Documentation
 * [English](https://smart-doc-group.github.io/)

src/main/java/com/ly/doc/builder/websocket/WebSocketDocBuilderTemplate.java

@@ -142,6 +142,8 @@ public Template buildWebSocketApiDocTemplate(WebSocketDoc webSocketDoc, ApiConfi
 		mapper.binding(TemplateVariable.AUTHOR.getVariable(), webSocketDoc.getAuthor());
 		mapper.binding(TemplateVariable.SUB_PROTOCOLS.getVariable(), webSocketDoc.getSubProtocols());
 		mapper.binding(TemplateVariable.WEBSOCKET_PATH_PARAMS.getVariable(), webSocketDoc.getPathParams());
+		mapper.binding(TemplateVariable.WEBSOCKET_MESSAGE_PARAMS.getVariable(), webSocketDoc.getMessageParams());
+		mapper.binding(TemplateVariable.WEBSOCKET_RESPONSE_PARAMS.getVariable(), webSocketDoc.getResponseParams());
 		return mapper;
 	}
 

src/main/java/com/ly/doc/constants/DocAnnotationConstants.java

@@ -197,6 +197,12 @@ public interface DocAnnotationConstants {
 	 */
 	String ON_OPEN = "OnOpen";
 
+	/**
+	 * `@javax.websocket.OnMessage` or `@jakarta.websocket.OnMessage` annotation name
+	 * {@code javax.websocket.OnMessage} {@code jakarta.websocket.OnMessage}
+	 */
+	String ON_MESSAGE = "OnMessage";
+
 	/**
 	 * `@javax.websocket.server.PathParam` or `@jakarta.websocket.PathParam` annotation
 	 * name {@code javax.websocket.server.PathParam}

src/main/java/com/ly/doc/constants/TemplateVariable.java

@@ -192,7 +192,19 @@ public enum TemplateVariable {
 	/**
 	 * webSocketPathParams
 	 */
-	WEBSOCKET_PATH_PARAMS("pathParams"),;
+	WEBSOCKET_PATH_PARAMS("pathParams"),
+
+	/**
+	 * webSocketMessageParams
+	 */
+	WEBSOCKET_MESSAGE_PARAMS("messageParams"),
+
+	/**
+	 * webSocketResponseParams
+	 */
+	WEBSOCKET_RESPONSE_PARAMS("responseParams"),
+
+	;
 
 	/**
 	 * variable

src/main/java/com/ly/doc/handler/IWebSocketRequestHandler.java

@@ -28,6 +28,7 @@
 import com.thoughtworks.qdox.model.JavaClass;
 import com.thoughtworks.qdox.model.expression.AnnotationValue;
 import com.thoughtworks.qdox.model.expression.AnnotationValueList;
+import com.thoughtworks.qdox.model.expression.TypeRef;
 
 import java.util.List;
 import java.util.Objects;
@@ -64,6 +65,29 @@ default ServerEndpoint handleServerEndpoint(JavaClass cls, JavaAnnotation javaAn
 			List<String> subProtocols = valueList.stream().map(Object::toString).collect(Collectors.toList());
 			builder.setSubProtocols(subProtocols);
 		}
+
+		// get decoders of annotation
+		AnnotationValue decodersOfAnnotation = javaAnnotation.getProperty("decoders");
+		if (Objects.nonNull(decodersOfAnnotation) && decodersOfAnnotation instanceof AnnotationValueList) {
+			List<AnnotationValue> valueList = ((AnnotationValueList) decodersOfAnnotation).getValueList();
+			List<String> decoders = valueList.stream()
+				.filter(i -> i instanceof TypeRef)
+				.map(i -> ((TypeRef) i).getType().getFullyQualifiedName())
+				.collect(Collectors.toList());
+			builder.setDecoders(decoders);
+		}
+
+		// get encoders of annotation
+		AnnotationValue encodersOfAnnotation = javaAnnotation.getProperty("encoders");
+		if (Objects.nonNull(encodersOfAnnotation) && encodersOfAnnotation instanceof AnnotationValueList) {
+			List<AnnotationValue> valueList = ((AnnotationValueList) encodersOfAnnotation).getValueList();
+			List<String> encoders = valueList.stream()
+				.filter(i -> i instanceof TypeRef)
+				.map(i -> ((TypeRef) i).getType().getFullyQualifiedName())
+				.collect(Collectors.toList());
+			builder.setEncoders(encoders);
+		}
+
 		return builder;
 	}
 

src/main/java/com/ly/doc/helper/DocBuildHelper.java

@@ -262,7 +262,7 @@ private Set<FileDiff> getChangedFiles(List<DiffEntry> diff, Set<String> uncommit
 	 */
 	private String toQualifiedName(String relativePath) {
 		// /dev/null is git default path when a file is added or deleted
-		if ("/dev/null".equals(relativePath)) {
+		if (DiffEntry.DEV_NULL.equals(relativePath)) {
 			return relativePath;
 		}
 

src/main/java/com/ly/doc/model/WebSocketDoc.java

@@ -20,12 +20,14 @@
  */
 package com.ly.doc.model;
 
+import java.util.Collections;
 import java.util.List;
 
 /**
  * the webSocket doc
  *
- * @author Lin222
+ * @author linwumingshi
+ * @since 3.0.3
  */
 public class WebSocketDoc extends ApiDoc {
 
@@ -41,6 +43,16 @@ public class WebSocketDoc extends ApiDoc {
 	 */
 	private List<ApiParam> pathParams;
 
+	/**
+	 * message param
+	 */
+	private List<ApiParam> messageParams;
+
+	/**
+	 * response param
+	 */
+	private List<List<ApiParam>> responseParams;
+
 	/**
 	 * webSocket url
 	 */
@@ -64,13 +76,37 @@ public void setSubProtocols(String subProtocols) {
 	}
 
 	public List<ApiParam> getPathParams() {
+		if (pathParams == null) {
+			return Collections.emptyList();
+		}
 		return pathParams;
 	}
 
 	public void setPathParams(List<ApiParam> pathParams) {
 		this.pathParams = pathParams;
 	}
 
+	public List<ApiParam> getMessageParams() {
+		if (messageParams == null) {
+			return Collections.emptyList();
+		}
+		return messageParams;
+	}
+
+	public WebSocketDoc setMessageParams(List<ApiParam> messageParams) {
+		this.messageParams = messageParams;
+		return this;
+	}
+
+	public List<List<ApiParam>> getResponseParams() {
+		return responseParams;
+	}
+
+	public WebSocketDoc setResponseParams(List<List<ApiParam>> responseParams) {
+		this.responseParams = responseParams;
+		return this;
+	}
+
 	public String getUri() {
 		return uri;
 	}

src/main/java/com/ly/doc/model/request/ServerEndpoint.java

@@ -40,8 +40,17 @@ public class ServerEndpoint {
 	 */
 	private List<String> subProtocols;
 
+	/**
+	 * the decoders class list of annotation
+	 */
+	private List<String> decoders;
+
+	/**
+	 * the encoders class list of annotation
+	 */
+	private List<String> encoders;
+
 	public ServerEndpoint() {
-		this.subProtocols = Collections.emptyList();
 	}
 
 	/**
@@ -56,18 +65,45 @@ public String getUrl() {
 		return url;
 	}
 
-	public List<String> getSubProtocols() {
-		return subProtocols;
-	}
-
 	public ServerEndpoint setUrl(String url) {
 		this.url = url;
 		return this;
 	}
 
+	public List<String> getSubProtocols() {
+		if (subProtocols == null) {
+			subProtocols = Collections.emptyList();
+		}
+		return subProtocols;
+	}
+
 	public ServerEndpoint setSubProtocols(List<String> subProtocols) {
 		this.subProtocols = subProtocols;
 		return this;
 	}
 
+	public List<String> getDecoders() {
+		if (decoders == null) {
+			decoders = Collections.emptyList();
+		}
+		return decoders;
+	}
+
+	public ServerEndpoint setDecoders(List<String> decoders) {
+		this.decoders = decoders;
+		return this;
+	}
+
+	public List<String> getEncoders() {
+		if (encoders == null) {
+			encoders = Collections.emptyList();
+		}
+		return encoders;
+	}
+
+	public ServerEndpoint setEncoders(List<String> encoders) {
+		this.encoders = encoders;
+		return this;
+	}
+
 }

src/main/java/com/ly/doc/template/IWebSocketDocBuildTemplate.java

@@ -33,6 +33,7 @@
  * websocket doc build template
  *
  * @author linwumingshi
+ * @since 3.0.3
  */
 public interface IWebSocketDocBuildTemplate<T extends WebSocketDoc> extends IDocBuildBaseTemplate {
 
@@ -47,7 +48,7 @@ default List<T> getWebSocketData(ProjectDocConfigBuilder projectBuilder) {
 		DocMapping.init();
 		DocBuildHelper docBuildHelper = DocBuildHelper.create(projectBuilder);
 
-		preRender(docBuildHelper);
+		this.preRender(docBuildHelper);
 
 		Collection<JavaClass> candidateClasses = this.getCandidateClasses(projectBuilder, docBuildHelper);