feat: add MCExcludeFromSchema annotation and migrate statusCode t… (#2388)

* feat: add `MCExcludeFromSchema` annotation and migrate `statusCode` to `status` in YAML tutorials and schemas - Introduced `MCExcludeFromSchema` annotation to allow exclusion of fields during schema generation. - Replaced `statusCode` with `status` across YAML tutorial and schema files for consistency. - Updated `JsonSchemaGenerator` and `AttributeInfo` to support exclusion logic based on the new annotation. * refactor: remove `MCExcludeFromSchema` annotation and migrate exclusion logic to `MCAttribute` * refactor: simplify exclusion method names and streamline annotation handling in `AttributeInfo` and `JsonSchemaGenerator` * refactor: remove redundant Javadoc tags in `AttributeInfo` methods * expose 'excludeFromJson' and 'deprecated' to help reference --------- Co-authored-by: Tobias Polley <mail@tobias-polley.de> Co-authored-by: Tobias Polley <polley@predic8.de>

Author: predic8

annot/src/main/java/com/predic8/membrane/annot/MCAttribute.java

@@ -19,11 +19,20 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Injects an XML attribute using a setter method.
+ * Annotation for marking a method to represent an attribute in the Membrane configuration.
+ * Primarily used for defining properties and their representation across different configuration grammars,
+ * such as JSON Schema or XML Schema (XSD).
+ *
+ * Methods annotated with this are typically setters with specific behavior or constraints
+ * controlled by the annotation's attributes.
+ *
+ * Attributes:
+ * - attributeName: Specifies the name of the attribute. If not defined, a default naming convention might apply.
+ * - excludeFromJson: Indicates whether the attribute should be excluded from JSON Schema representation (default is false).
  */
 @Target(METHOD)
 @Retention(RUNTIME)
 public @interface MCAttribute {
-
 String attributeName() default "";
+ boolean excludeFromJson() default false; // excludes from JSON Schema (YAML)
 }

annot/src/main/java/com/predic8/membrane/annot/generator/HelpReference.java

@@ -123,6 +123,7 @@ private void handle(Model m, MainInfo main, ElementInfo ei) throws XMLStreamExce
 xew.writeAttribute("mixed", "true");
 xew.writeAttribute("topLevel", Boolean.toString(ei.getAnnotation().topLevel()));
 xew.writeAttribute("id", ei.getId());
+ xew.writeAttribute("deprecated", Boolean.toString(ei.isDeprecated()));
 if (!ei.getAnnotation().topLevel()) {
 String primaryParentId = getPrimaryParentId(m, main, ei);
 if (primaryParentId != null)
@@ -198,6 +199,7 @@ private void handle(Model m, MainInfo main, ChildElementInfo cei) throws XMLStre
 xew.writeStartElement("child");
 xew.writeAttribute("min", cei.isRequired() ? "1" : "0");
 xew.writeAttribute("max", cei.isList() ? "unbounded" : "1");
+ xew.writeAttribute("deprecated", Boolean.toString(cei.isDeprecated()));
 
 handleDoc(cei);
 
@@ -228,6 +230,8 @@ private void handle(AttributeInfo ai) throws XMLStreamException {
 xew.writeStartElement("attribute");
 xew.writeAttribute("name", ai.getXMLName());
 xew.writeAttribute("required", Boolean.toString(ai.isRequired()));
+ xew.writeAttribute("excludeFromJson", Boolean.toString(ai.excludedFromJsonSchema()));
+ xew.writeAttribute("deprecated", Boolean.toString(ai.isDeprecated()));
 handleDoc(ai);
 xew.writeEndElement();
 }

annot/src/main/java/com/predic8/membrane/annot/generator/JsonSchemaGenerator.java

@@ -175,6 +175,11 @@ private FileObject createFile(MainInfo main) throws IOException {
 
  private void processMCAttributes(ElementInfo i, SchemaObject so) {
  i.getAis().forEach(ai -> {
+
+ // skip attributes marked with @MCExcludeFromSchema
+ if (ai.excludedFromJsonSchema())
+ return;
+
  // hide id only on top-level elements
  if ("id".equals(ai.getXMLName()) && i.getAnnotation().topLevel()) {
  return;
@@ -253,7 +258,6 @@ boolean isFlowFromWebSocket(ChildElementInfo cei) {
  }
 
  private AbstractSchema<?> processList(ElementInfo i, AbstractSchema<?> so, ChildElementInfo cei, ArrayList<SchemaObject> sos) {
-
  SchemaObject items = object("items");
 
  if (shouldGenerateParserType(cei)) {
@@ -293,7 +297,6 @@ private void addChildsAsProperties(Model m, MainInfo main, ChildElementInfo cei,
  .ref("#/$defs/" + ei.getXSDTypeName(m)))
  .description(getDescriptionContent(ei))
  .required(cei.isRequired());
-
  }
  }
 

annot/src/main/java/com/predic8/membrane/annot/model/AbstractJavadocedInfo.java

@@ -14,7 +14,9 @@
 package com.predic8.membrane.annot.model;
 
 import javax.annotation.processing.ProcessingEnvironment;
+import javax.lang.model.element.AnnotationMirror;
 import javax.lang.model.element.Element;
+import javax.lang.model.element.TypeElement;
 
 import com.predic8.membrane.annot.MCAttribute;
 import com.predic8.membrane.annot.MCElement;
@@ -24,7 +26,8 @@
  * Common behavior of Javadoc handling for {@link MCAttribute}, {@link MCElement}, etc.
  */
 public abstract class AbstractJavadocedInfo {
-private Element docedE;
+ public static final String JAVA_LANG_DEPRECATED = "java.lang.Deprecated";
+ private Element docedE;
 private boolean docGenerated;
 private Doc doc;
 
@@ -50,4 +53,11 @@ public Doc getDoc(ProcessingEnvironment processingEnv) {
 return doc = new Doc(processingEnv, javadoc, getDocedE());
 }
 
+ public boolean isDeprecated() {
+ for (AnnotationMirror am : docedE.getAnnotationMirrors())
+ if (((TypeElement) am.getAnnotationType().asElement()).getQualifiedName().toString().equals(JAVA_LANG_DEPRECATED))
+ return true;
+ return false;
+ }
+
 }

annot/src/main/java/com/predic8/membrane/annot/model/AttributeInfo.java

@@ -75,7 +75,6 @@ public String getSchemaType(Types typeUtils) {
  /**
  * It is not checked how many values the enum has. There are enums link validateRequests of OpenAPIValidator
  * that have more than 2 values but they are also booleans at the configuration level
- * @return
  */
  private boolean isEnumBoolean(Types typeUtils) {
  return getEnumValues(typeUtils).contains("TRUE") && getEnumValues(typeUtils).contains("FALSE");
@@ -98,7 +97,6 @@ public boolean isBeanReference(Types typeUtils) {
 
  /**
  * Sets as side effect instance variables e.g. xsdType, isEnum, isBeanReference.
- * @param typeUtils
  */
  private void analyze(Types typeUtils) {
  if (xsdType != null) // already analyzed?
@@ -195,4 +193,13 @@ public boolean isRequired() {
  public void setRequired(boolean required) {
  this.required = required;
  }
+
+ /**
+ * Determines whether the current field or method should be excluded from the JSON schema during schema generation.
+ * @return {@code true} if the field or method is excluded from the JSON schema; {@code false} otherwise.
+ */
+ public boolean excludedFromJsonSchema() {
+ return annotation != null && annotation.excludeFromJson();
+ }
+
 }

core/src/main/java/com/predic8/membrane/core/interceptor/flow/ReturnInterceptor.java

@@ -39,7 +39,7 @@
  * 2. If there is no response in the exchange, the body and contentType of the request is copied into a new response.
  * </p>
  * <p>
- * The options <i>statusCode</i> and <i>contentType</i> will overwrite the values from the messages.
+ * The options <i>status</i> and <i>contentType</i> will overwrite the values from the messages.
  * </p>
  * <p>
  * This plugin is useful together with the template plugin. See examples/template.
@@ -51,7 +51,7 @@ public class ReturnInterceptor extends AbstractInterceptor {
 
  private static final Logger log = LoggerFactory.getLogger(ReturnInterceptor.class.getName());
 
- private int statusCode = 200;
+ private int status = 200;
  private String contentType = null;
 
  @Override
@@ -76,9 +76,9 @@ private Response getOrCreateResponse(Exchange exc) throws IOException {
  response = createResponseFromRequest(exc);
  }
 
- if (statusCode != 0) {
- response.setStatusCode(statusCode);
- response.setStatusMessage(getMessageForStatusCode(statusCode));
+ if (status != 0) {
+ response.setStatusCode(status);
+ response.setStatusMessage(getMessageForStatusCode(status));
  }
 
  if (contentType!=null) {
@@ -92,7 +92,7 @@ private Response getOrCreateResponse(Exchange exc) throws IOException {
  }
 
  private Response createResponseFromRequest(Exchange exc) throws IOException {
- Response.ResponseBuilder builder = new Response.ResponseBuilder().status(statusCode);
+ Response.ResponseBuilder builder = new Response.ResponseBuilder().status(status);
  String reqContentType = exc.getRequest().getHeader().getContentType();
  if (reqContentType != null) {
  builder.contentType(reqContentType);
@@ -112,7 +112,7 @@ public String getDisplayName() {
 
  @Override
  public String getShortDescription() {
- return (contentType != null) ? format("Sends a response with a status code of %d and a content type of %s.", statusCode, contentType) : format("Sends a response with a status code of %d.", statusCode);
+ return (contentType != null) ? format("Sends a response with a status code of %d and a content type of %s.", status, contentType) : format("Sends a response with a status code of %d.", status);
  }
 
  @Override
@@ -121,21 +121,38 @@ public EnumSet<Flow> getAppliedFlow() {
  }
 
  /**
- * @description HTTP status code to be returned.
+ * @deprecated Use status instead.
+ * @description HTTP status code to be returned. statusCode is kept only for backward compatibility use status instead.
  * @default 200
  * @example 400
  */
- @MCAttribute
+ @Deprecated
+ @MCAttribute(excludeFromJson = true)
  public void setStatusCode(int statusCode) {
- this.statusCode = statusCode;
+ // Is excluded from the JSON schema. But will be included in the XSD schema.
+ this.status = statusCode;
  }
 
  public int getStatusCode() {
- return statusCode;
+ return status;
+ }
+
+ /**
+ * @description HTTP status code to be returned.
+ * @default 200
+ * @example 400
+ */
+ @MCAttribute
+ public void setStatus(int status) {
+ this.status = status;
+ }
+
+ public int getStatus() {
+ return status;
  }
 
  /**
- * @description Content type of the response. If not set, the content type of the request (if available) or no content type will be used.
+ * @description Content-Type of the response. If not set, the content type of the request (if available) or no content type will be used.
  * @default null
  * @example application/json; charset=utf-8
  */

core/src/test/java/com/predic8/membrane/core/config/spring/k8s/EnvelopeTest.java

@@ -83,7 +83,7 @@ void routerConfConfig() {
  contentType: application/json
  src: '{ "ok": 1 }'
  - return:
- statusCode: 200
+ status: 200
  ---
  api:
  port: 2000

distribution/examples/extending-membrane/error-handling/custom-error-messages/apis.yaml

@@ -104,7 +104,7 @@ api:
  contentType: text/plain
  src: Ordinary error!
  - return:
- statusCode: 500
+ status: 500
  - if:
  test: param.case == 'd'
  flow:
@@ -115,6 +115,6 @@ api:
  <description>XML Fehler Meldung vom Backend!</description>
  </failure>
  - return:
- statusCode: 500
+ status: 500
  # SOAP Service Mock for Debugging
  - sampleSoapService: {}

distribution/examples/extending-membrane/if/apis.yaml

@@ -69,4 +69,4 @@ api:
  - template:
  src: Success
  - return:
- statusCode: 302
+ status: 302

distribution/examples/monitoring-tracing/prometheus/apis.yaml

@@ -11,20 +11,20 @@ api:
  port: 2001
  flow:
  - return:
- statusCode: 200
+ status: 200
 
 ---
 
 api:
  port: 2002
  flow:
  - return:
- statusCode: 404
+ status: 404
 
 ---
 
 api:
  port: 2003
  flow:
  - return:
- statusCode: 500
+ status: 500