Skip to content

The Unified and Autonomous Development Platform

feat: Json version of API help to be consumed by coding agents

Robin Shen658fcdcc5c2b
diff --git a/server-core/src/main/java/io/onedev/server/rest/AnonymousCheckFilter.java b/server-core/src/main/java/io/onedev/server/rest/AnonymousCheckFilter.java
index 66ea2ad4fb..410708e722 100644
--- a/server-core/src/main/java/io/onedev/server/rest/AnonymousCheckFilter.java
+++ b/server-core/src/main/java/io/onedev/server/rest/AnonymousCheckFilter.java
@@ -12,11 +12,12 @@ import jakarta.ws.rs.ext.Provider;
import org.apache.shiro.authz.UnauthenticatedException;
-import io.onedev.server.service.SettingService;
-import io.onedev.server.rest.resource.TriggerJobResource;
-import io.onedev.server.rest.resource.ServerResource;
import io.onedev.server.rest.annotation.Api;
+import io.onedev.server.rest.resource.ApiHelpResource;
+import io.onedev.server.rest.resource.ServerResource;
+import io.onedev.server.rest.resource.TriggerJobResource;
import io.onedev.server.security.SecurityUtils;
+import io.onedev.server.service.SettingService;
@Provider
public class AnonymousCheckFilter implements ContainerRequestFilter {
@@ -37,7 +38,9 @@ public class AnonymousCheckFilter implements ContainerRequestFilter {
@Override
public void filter(ContainerRequestContext requestContext) throws IOException {
Api api = resourceInfo.getResourceClass().getAnnotation(Api.class);
- if ((api == null || !api.internal()) && SecurityUtils.isAnonymous()
+ // JSON help is hidden from the resource list, but follows the help pages' access policy.
+ if ((api == null || !api.internal() || resourceInfo.getResourceClass() == ApiHelpResource.class)
+ && SecurityUtils.isAnonymous()
&& resourceInfo.getResourceClass() != TriggerJobResource.class
&& resourceInfo.getResourceClass() != ServerResource.class) {
String method = request.getMethod();
diff --git a/server-core/src/main/java/io/onedev/server/rest/ApiHelpJson.java b/server-core/src/main/java/io/onedev/server/rest/ApiHelpJson.java
new file mode 100644
index 0000000000..0bd19a31f6
--- /dev/null
+++ b/server-core/src/main/java/io/onedev/server/rest/ApiHelpJson.java
@@ -0,0 +1,297 @@
+package io.onedev.server.rest;
+
+import static io.onedev.server.web.page.help.ApiHelpUtils.*;
+import static io.onedev.server.web.page.help.ValueInfo.Origin.*;
+
+import java.io.InputStream;
+import java.lang.reflect.Array;
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+import java.lang.reflect.Parameter;
+import java.lang.reflect.Type;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Date;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.StreamingOutput;
+
+import org.jsoup.Jsoup;
+import org.jspecify.annotations.Nullable;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.onedev.commons.utils.WordUtils;
+import io.onedev.server.OneDev;
+import io.onedev.server.model.AbstractEntity;
+import io.onedev.server.rest.annotation.Api;
+import io.onedev.server.rest.annotation.EntityCreate;
+import io.onedev.server.util.ReflectionUtils;
+import io.onedev.server.web.page.help.ExampleProvider;
+import io.onedev.server.web.page.help.JsonMember;
+import io.onedev.server.web.page.help.ValueInfo.Origin;
+
+/** Builds JSON help from the same metadata and examples as the help pages. */
+public class ApiHelpJson {
+
+ public static final String PATH = "/~api/help";
+
+ private final Map<String, Object> definitions = new LinkedHashMap<>();
+
+ public Map<String, Object> getResources(String serverUrl) {
+ Map<String, Object> result = new LinkedHashMap<>();
+ result.put("title", "RESTful API Help");
+ result.put("baseUrl", serverUrl + "/~api");
+ result.put("authentication", "When anonymous access is disabled or lacks permission, authenticate with "
+ + "a user name and password (or access token) via the HTTP Basic authorization header.");
+ result.put("usage", "Follow each resource's help URL to list its methods, then each method's help URL "
+ + "for parameters, request/response examples and schemas. Examples are illustrative; replace example values before calling the API.");
+ result.put("resources", getResourceClasses().stream().map(this::resourceSummary).toList());
+ return result;
+ }
+
+ public Map<String, Object> getResource(Class<?> resourceClass) {
+ var result = resourceSummary(resourceClass);
+ result.remove("id");
+ result.remove("help");
+ result.put("methods", getResourceMethods(resourceClass).stream()
+ .map(method -> methodSummary(resourceClass, method)).toList());
+ return result;
+ }
+
+ public Map<String, Object> getMethod(Class<?> resourceClass, Method method) {
+ definitions.clear();
+ var result = methodSummary(resourceClass, method);
+ result.remove("help");
+ List<Map<String, Object>> pathParams = new ArrayList<>();
+ List<Map<String, Object>> queryParams = new ArrayList<>();
+ for (var param: method.getParameters()) {
+ if (param.isAnnotationPresent(PathParam.class))
+ pathParams.add(parameter(method, param, true));
+ else if (param.isAnnotationPresent(QueryParam.class))
+ queryParams.add(parameter(method, param, false));
+ }
+ result.put("pathParameters", pathParams);
+ result.put("queryParameters", queryParams);
+ var bodyParam = getRequestBodyParam(method);
+ result.put("requestBody", bodyParam != null
+ ? body(resourceClass, bodyParam.getParameterizedType(), bodyParam.getAnnotation(Api.class), getPostValueOrigin(method))
+ : null);
+ Map<String, Object> success = new LinkedHashMap<>();
+ success.put("statusCode", 200);
+ success.put("body", method.getReturnType() != Response.class && method.getReturnType() != void.class
+ ? body(resourceClass, method.getGenericReturnType(), method.getAnnotation(Api.class), READ_BODY) : null);
+ if (method.getReturnType() == Long.class && bodyParam != null) {
+ var createdType = bodyParam.getType();
+ var entityCreate = createdType.getAnnotation(EntityCreate.class);
+ if (entityCreate != null)
+ createdType = entityCreate.value();
+ if (AbstractEntity.class.isAssignableFrom(createdType))
+ success.put("description", "Id of created " + WordUtils.uncamel(createdType.getSimpleName()).toLowerCase());
+ }
+ result.put("response", Map.of("success", success, "failure", Map.of(
+ "statusCode", "Non-200 status indicating the error type", "contentType", MediaType.TEXT_PLAIN,
+ "description", "Error detail")));
+ if (!definitions.isEmpty())
+ result.put("$defs", definitions);
+ return result;
+ }
+
+ private Map<String, Object> resourceSummary(Class<?> resourceClass) {
+ Map<String, Object> result = new LinkedHashMap<>();
+ result.put("id", resourceClass.getName());
+ result.put("title", getResourceTitle(resourceClass));
+ result.put("description", text(getResourceDescription(resourceClass)));
+ result.put("path", resourceClass.getAnnotation(Path.class).value());
+ result.put("help", PATH + "/" + resourceClass.getName());
+ return result;
+ }
+
+ private Map<String, Object> methodSummary(Class<?> resourceClass, Method method) {
+ Map<String, Object> result = new LinkedHashMap<>();
+ result.put("title", getMethodTitle(method));
+ result.put("description", text(getMethodDescription(method)));
+ result.put("httpMethod", getHttpMethod(method));
+ result.put("path", "/~api" + getResourcePath(resourceClass, method));
+ result.put("help", PATH + "/" + resourceClass.getName() + "/" + method.getName());
+ return result;
+ }
+
+ private Map<String, Object> parameter(Method method, Parameter param, boolean path) {
+ var name = path ? param.getAnnotation(PathParam.class).value() : param.getAnnotation(QueryParam.class).value();
+ var origin = path ? PATH_PLACEHOLDER : QUERY_PARAM;
+ Map<String, Object> result = new LinkedHashMap<>();
+ result.put("name", name);
+ var description = getDescription(param);
+ result.put("description", description != null ? text(description) : WordUtils.capitalize(WordUtils.uncamel(name)));
+ result.put("required", path || ParamCheckFilter.isRequired(param));
+ result.put("schema", schema(param.getParameterizedType(), origin));
+ result.put("example", example(exampleValue(method.getDeclaringClass(), param.getParameterizedType(),
+ param.getAnnotation(Api.class), origin), param.getParameterizedType(), origin));
+ if (!path && Collection.class.isAssignableFrom(param.getType()))
+ result.put("serialization", "Repeat the query parameter for each value");
+ return result;
+ }
+
+ private Map<String, Object> body(Class<?> resourceClass, Type type, @Nullable Api api, Origin origin) {
+ Map<String, Object> result = new LinkedHashMap<>();
+ var clazz = ReflectionUtils.getClass(type);
+ if (InputStream.class.isAssignableFrom(clazz) || StreamingOutput.class.isAssignableFrom(clazz)) {
+ result.put("contentType", MediaType.APPLICATION_OCTET_STREAM);
+ } else {
+ result.put("contentType", MediaType.APPLICATION_JSON);
+ try {
+ result.put("example", example(exampleValue(resourceClass, type, api, origin), type, origin));
+ } catch (RuntimeException e) {
+ // Third-party types or contributed example providers may not support example generation.
+ // Keep the operation discoverable, without passing off a partial example as a valid one.
+ result.put("exampleUnavailable", "An example could not be generated from the API metadata.");
+ }
+ result.put("schema", schema(type, origin));
+ }
+ return result;
+ }
+
+ private Object exampleValue(Class<?> declaringClass, Type type, @Nullable Api api, Origin origin) {
+ var value = new ExampleProvider(declaringClass, api).getExample();
+ var clazz = ReflectionUtils.getClass(type);
+ if (value instanceof String && (clazz.isPrimitive() || Number.class.isAssignableFrom(clazz) || clazz == Boolean.class))
+ return OneDev.getInstance(ObjectMapper.class).convertValue(value, clazz);
+ return value != null ? value : getExampleValue(type, origin);
+ }
+
+ // Serialize examples like ExampleValuePanel: omit input IDs, use association IDs,
+ // preserve display order, and include the discriminator for abstract declared types.
+ private Object example(@Nullable Object value, @Nullable Type type, Origin origin) {
+ if (value == null || value instanceof String || value instanceof Number || value instanceof Boolean
+ || value instanceof Date || value instanceof Enum)
+ return OneDev.getInstance(ObjectMapper.class).valueToTree(value);
+ if (value instanceof Collection) {
+ var elementType = type != null ? ReflectionUtils.getCollectionElementType(type) : null;
+ return ((Collection<?>) value).stream().map(it -> example(it, elementType, origin)).toList();
+ }
+ if (value.getClass().isArray()) {
+ List<Object> values = new ArrayList<>();
+ for (int i = 0; i < Array.getLength(value); i++)
+ values.add(example(Array.get(value, i), value.getClass().getComponentType(), origin));
+ return values;
+ }
+ Map<String, Object> result = new LinkedHashMap<>();
+ if (value instanceof Map) {
+ var valueType = type != null ? ReflectionUtils.getMapValueType(type) : null;
+ ((Map<?, ?>) value).forEach((key, item) -> result.put(key.toString(), example(item, valueType, origin)));
+ } else {
+ if (type != null && isPolymorphic(ReflectionUtils.getClass(type)))
+ result.put("@type", value.getClass().getSimpleName());
+ for (var member: members(value.getClass(), origin)) {
+ var memberValue = member.getValue(value);
+ if (isAssociation(member))
+ result.put(member.getName() + "Id", memberValue != null ? ((AbstractEntity) memberValue).getId() : null);
+ else
+ result.put(member.getName(), example(memberValue, member.getGenericType(), origin));
+ }
+ }
+ return result;
+ }
+
+ private Map<String, Object> schema(@Nullable Type type, Origin origin) {
+ Map<String, Object> result = new LinkedHashMap<>();
+ var clazz = type != null ? ReflectionUtils.getClass(type) : Object.class;
+ if (clazz == null || clazz == Object.class || clazz == java.io.Serializable.class)
+ return result;
+ if (clazz == String.class || clazz == char.class || clazz == Character.class) {
+ result.put("type", "string");
+ } else if (clazz == boolean.class || clazz == Boolean.class) {
+ result.put("type", "boolean");
+ } else if (clazz.isPrimitive() || Number.class.isAssignableFrom(clazz)) {
+ result.put("type", clazz == float.class || clazz == double.class || clazz == Float.class || clazz == Double.class
+ ? "number" : "integer");
+ } else if (Date.class.isAssignableFrom(clazz)) {
+ result.put("type", "string");
+ result.put("format", "date-time");
+ } else if (clazz.isEnum()) {
+ result.put("type", "string");
+ List<String> values = new ArrayList<>();
+ for (var constant: clazz.getEnumConstants())
+ values.add(((Enum<?>) constant).name());
+ result.put("enum", values);
+ } else if (Collection.class.isAssignableFrom(clazz) || clazz.isArray()) {
+ result.put("type", "array");
+ result.put("items", schema(clazz.isArray() ? clazz.getComponentType() : ReflectionUtils.getCollectionElementType(type), origin));
+ } else if (Map.class.isAssignableFrom(clazz)) {
+ result.put("type", "object");
+ result.put("additionalProperties", schema(ReflectionUtils.getMapValueType(type), origin));
+ } else if (clazz.getName().startsWith("java.")) {
+ // Do not infer a JSON representation from private JDK implementation fields.
+ result.put("javaType", clazz.getName());
+ } else {
+ var key = clazz.getName() + "." + origin.name();
+ result.put("$ref", "#/$defs/" + key);
+ if (!definitions.containsKey(key)) {
+ Map<String, Object> definition = new LinkedHashMap<>();
+ definitions.put(key, definition); // Register before visiting recursive members.
+ var description = getDescription(clazz);
+ if (description != null)
+ definition.put("description", text(description));
+ if (isPolymorphic(clazz)) {
+ List<Object> alternatives = new ArrayList<>();
+ for (var implementation: getImplementations(clazz)) {
+ alternatives.add(Map.of("allOf", List.of(schema(implementation, origin), Map.of(
+ "type", "object", "properties", Map.of("@type", Map.of("const", implementation.getSimpleName())),
+ "required", List.of("@type")))));
+ }
+ definition.put("oneOf", alternatives);
+ } else {
+ definition.put("type", "object");
+ Map<String, Object> properties = new LinkedHashMap<>();
+ for (var member: members(clazz, origin)) {
+ var property = schema(isAssociation(member) ? Long.class : member.getGenericType(), origin);
+ var memberDescription = getDescription(member);
+ if (memberDescription != null)
+ property.put("description", text(memberDescription));
+ properties.put(member.getName() + (isAssociation(member) ? "Id" : ""), property);
+ }
+ definition.put("properties", properties);
+ }
+ }
+ }
+ return result;
+ }
+
+ private List<JsonMember> members(Class<?> clazz, Origin origin) {
+ return getJsonMembers(clazz, origin).stream()
+ .filter(it -> origin != CREATE_BODY && origin != UPDATE_BODY || !it.isAnnotationPresent(Id.class)).toList();
+ }
+
+ private boolean isAssociation(JsonMember member) {
+ return member.isAnnotationPresent(ManyToOne.class) || member.isAnnotationPresent(JoinColumn.class);
+ }
+
+ private boolean isPolymorphic(Class<?> clazz) {
+ return Modifier.isAbstract(clazz.getModifiers()) && !clazz.getName().startsWith("java.")
+ && !clazz.getName().startsWith("javax.");
+ }
+
+ @Nullable
+ private String text(@Nullable String html) {
+ if (html == null)
+ return null;
+ var document = Jsoup.parseBodyFragment(html);
+ for (var link: document.select("a[href]")) {
+ var href = link.attr("href");
+ link.appendText(" (" + href + ")");
+ }
+ return document.text();
+ }
+
+}
diff --git a/server-core/src/main/java/io/onedev/server/rest/resource/ApiHelpResource.java b/server-core/src/main/java/io/onedev/server/rest/resource/ApiHelpResource.java
new file mode 100644
index 0000000000..0795adca4d
--- /dev/null
+++ b/server-core/src/main/java/io/onedev/server/rest/resource/ApiHelpResource.java
@@ -0,0 +1,64 @@
+package io.onedev.server.rest.resource;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.NotFoundException;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.onedev.server.rest.ApiHelpJson;
+import io.onedev.server.rest.annotation.Api;
+import io.onedev.server.service.SettingService;
+import io.onedev.server.web.page.help.ApiHelpUtils;
+
+/** Machine-readable counterpart of the resource / method hierarchy in the help UI. */
+@Api(internal = true)
+@Path("/help")
+@Produces(MediaType.APPLICATION_JSON)
+@Singleton
+public class ApiHelpResource {
+
+ private final SettingService settingService;
+
+ @Inject
+ public ApiHelpResource(SettingService settingService) {
+ this.settingService = settingService;
+ }
+
+ @GET
+ public Map<String, Object> getResources() {
+ return new ApiHelpJson().getResources(settingService.getSystemSetting().getServerUrl());
+ }
+
+ @GET
+ @Path("/{resource}")
+ public Map<String, Object> getResource(@PathParam("resource") String resource) {
+ return new ApiHelpJson().getResource(findResource(resource));
+ }
+
+ @GET
+ @Path("/{resource}/{method}")
+ public Map<String, Object> getMethod(@PathParam("resource") String resource, @PathParam("method") String method) {
+ var resourceClass = findResource(resource);
+ for (var resourceMethod: ApiHelpUtils.getResourceMethods(resourceClass)) {
+ if (resourceMethod.getName().equals(method))
+ return new ApiHelpJson().getMethod(resourceClass, resourceMethod);
+ }
+ throw new NotFoundException("API method not found: " + method);
+ }
+
+ private Class<?> findResource(String resource) {
+ // Resolve only documented, registered resources. Never load a caller-supplied class.
+ for (var resourceClass: ApiHelpUtils.getResourceClasses()) {
+ if (resourceClass.getName().equals(resource))
+ return resourceClass;
+ }
+ throw new NotFoundException("API resource not found: " + resource);
+ }
+
+}
diff --git a/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpPage.html b/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpPage.html
index 56985cb883..780ed96717 100644
--- a/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpPage.html
+++ b/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpPage.html
@@ -2,6 +2,11 @@
<div class="api-help card m-2 m-sm-5">
<div class="card-body">
<wicket:child></wicket:child>
+ <div class="mt-4 text-muted">
+ <wicket:svg href="bulb" class="icon"></wicket:svg>
+ <wicket:t>A JSON version of this API help is available for AI agents at</wicket:t>
+ <a wicket:id="jsonHelp"></a>.
+ </div>
</div>
</div>
-</wicket:extend>
\ No newline at end of file
+</wicket:extend>
diff --git a/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpPage.java b/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpPage.java
index f1c3734899..cb071b11ba 100644
--- a/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpPage.java
+++ b/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpPage.java
@@ -4,20 +4,15 @@ import static io.onedev.server.web.translation.Translation._T;
import java.lang.reflect.Method;
-import org.jspecify.annotations.Nullable;
-import jakarta.ws.rs.GET;
-import jakarta.ws.rs.POST;
-import jakarta.ws.rs.PUT;
-
-import org.apache.commons.lang.StringUtils;
import org.apache.wicket.Component;
import org.apache.wicket.markup.head.CssHeaderItem;
import org.apache.wicket.markup.head.IHeaderResponse;
import org.apache.wicket.markup.html.basic.Label;
+import org.apache.wicket.markup.html.link.ExternalLink;
import org.apache.wicket.request.mapper.parameter.PageParameters;
+import org.jspecify.annotations.Nullable;
-import io.onedev.commons.utils.WordUtils;
-import io.onedev.server.rest.annotation.Api;
+import io.onedev.server.rest.ApiHelpJson;
import io.onedev.server.web.page.layout.LayoutPage;
public abstract class ApiHelpPage extends LayoutPage {
@@ -26,6 +21,12 @@ public abstract class ApiHelpPage extends LayoutPage {
super(params);
}
+ @Override
+ protected void onInitialize() {
+ super.onInitialize();
+ add(new ExternalLink("jsonHelp", ApiHelpJson.PATH, ApiHelpJson.PATH));
+ }
+
@Override
protected String getPageTitle() {
return _T("RESTful API Help");
@@ -37,59 +38,25 @@ public abstract class ApiHelpPage extends LayoutPage {
}
protected String getResourceTitle(Class<?> resourceClass) {
- var api = resourceClass.getAnnotation(Api.class);
- if (api != null && api.name().length() != 0) {
- return api.name();
- } else {
- return WordUtils.capitalize(
- WordUtils.uncamel(
- StringUtils.substringBeforeLast(
- resourceClass.getSimpleName(), "Resource")));
- }
+ return ApiHelpUtils.getResourceTitle(resourceClass);
}
-
+
@Nullable
protected String getResourceDescription(Class<?> resourceClass) {
- String description = "";
- Api api = resourceClass.getAnnotation(Api.class);
- if (api != null && api.description().length() != 0)
- description = api.description();
- if (description.length() != 0)
- return description;
- else
- return null;
+ return ApiHelpUtils.getResourceDescription(resourceClass);
}
-
+
protected String getMethodTitle(Method resourceMethod) {
- var api = resourceMethod.getAnnotation(Api.class);
- if (api != null && api.name().length() != 0) {
- return api.name();
- } else {
- return WordUtils.capitalize(WordUtils.uncamel(resourceMethod.getName()));
- }
+ return ApiHelpUtils.getMethodTitle(resourceMethod);
}
@Nullable
protected String getMethodDescription(Method resourceMethod) {
- String description = "";
- Api api = resourceMethod.getAnnotation(Api.class);
- if (api != null && api.description().length() != 0)
- description = api.description();
- if (description.length() != 0)
- return description;
- else
- return null;
+ return ApiHelpUtils.getMethodDescription(resourceMethod);
}
-
+
protected String getHttpMethod(Method resourceMethod) {
- if (resourceMethod.getAnnotation(GET.class) != null)
- return "GET";
- else if (resourceMethod.getAnnotation(POST.class) != null)
- return "POST";
- else if (resourceMethod.getAnnotation(PUT.class) != null)
- return "PUT";
- else
- return "DELETE";
+ return ApiHelpUtils.getHttpMethod(resourceMethod);
}
@Override
diff --git a/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpUtils.java b/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpUtils.java
index 2fd20e4925..c38a91a574 100644
--- a/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpUtils.java
+++ b/server-core/src/main/java/io/onedev/server/web/page/help/ApiHelpUtils.java
@@ -6,10 +6,12 @@ import static io.onedev.server.web.page.help.ValueInfo.Origin.UPDATE_BODY;
import static java.util.Comparator.comparing;
import java.io.Serializable;
+import java.lang.reflect.AnnotatedElement;
import java.lang.reflect.Field;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
+import java.lang.reflect.Parameter;
import java.lang.reflect.Type;
import java.util.ArrayList;
import java.util.Collection;
@@ -26,7 +28,17 @@ import jakarta.persistence.ManyToOne;
import jakarta.persistence.OneToMany;
import jakarta.persistence.OneToOne;
import jakarta.persistence.Transient;
+import jakarta.ws.rs.DELETE;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.Context;
+import org.glassfish.jersey.server.ResourceConfig;
+import org.jspecify.annotations.Nullable;
import org.objenesis.ObjenesisStd;
import com.fasterxml.jackson.annotation.JsonIgnore;
@@ -37,6 +49,8 @@ import com.google.common.collect.Sets;
import edu.emory.mathcs.backport.java.util.Collections;
import io.onedev.commons.loader.ImplementationRegistry;
+import io.onedev.commons.utils.StringUtils;
+import io.onedev.commons.utils.WordUtils;
import io.onedev.server.OneDev;
import io.onedev.server.model.AbstractEntity;
import io.onedev.server.rest.annotation.Api;
@@ -50,6 +64,98 @@ import io.onedev.server.web.page.project.setting.ProjectSettingContribution;
public class ApiHelpUtils {
+ public static String getResourceTitle(Class<?> resourceClass) {
+ var api = resourceClass.getAnnotation(Api.class);
+ if (api != null && api.name().length() != 0) {
+ return api.name();
+ } else {
+ return WordUtils.capitalize(
+ WordUtils.uncamel(
+ StringUtils.substringBeforeLast(
+ resourceClass.getSimpleName(), "Resource")));
+ }
+ }
+
+ @Nullable
+ public static String getResourceDescription(Class<?> resourceClass) {
+ return getDescription(resourceClass);
+ }
+
+ public static String getMethodTitle(Method resourceMethod) {
+ var api = resourceMethod.getAnnotation(Api.class);
+ if (api != null && api.name().length() != 0) {
+ return api.name();
+ } else {
+ return WordUtils.capitalize(WordUtils.uncamel(resourceMethod.getName()));
+ }
+ }
+
+ @Nullable
+ public static String getMethodDescription(Method resourceMethod) {
+ return getDescription(resourceMethod);
+ }
+
+ @Nullable
+ public static String getDescription(AnnotatedElement element) {
+ var api = element.getAnnotation(Api.class);
+ return api != null && !api.description().isEmpty() ? api.description() : null;
+ }
+
+ public static String getHttpMethod(Method resourceMethod) {
+ if (resourceMethod.getAnnotation(GET.class) != null)
+ return "GET";
+ else if (resourceMethod.getAnnotation(POST.class) != null)
+ return "POST";
+ else if (resourceMethod.getAnnotation(PUT.class) != null)
+ return "PUT";
+ else
+ return "DELETE";
+ }
+
+ public static List<Class<?>> getResourceClasses() {
+ List<Class<?>> resources = new ArrayList<>();
+ for (var clazz: OneDev.getInstance(ResourceConfig.class).getClasses()) {
+ var api = clazz.getAnnotation(Api.class);
+ if (clazz.isAnnotationPresent(Path.class) && (api == null || !api.internal()))
+ resources.add(clazz);
+ }
+ resources.sort(comparing(ApiHelpUtils::getResourceTitle));
+ return resources;
+ }
+
+ public static List<Method> getResourceMethods(Class<?> resourceClass) {
+ List<Method> methods = new ArrayList<>();
+ for (var method: resourceClass.getMethods()) {
+ if (method.isAnnotationPresent(GET.class) || method.isAnnotationPresent(POST.class)
+ || method.isAnnotationPresent(PUT.class) || method.isAnnotationPresent(DELETE.class))
+ methods.add(method);
+ }
+ methods.sort(new ApiComparator());
+ return methods;
+ }
+
+ @Nullable
+ public static Parameter getRequestBodyParam(Method method) {
+ for (var param: method.getParameters()) {
+ if (!param.isAnnotationPresent(PathParam.class) && !param.isAnnotationPresent(QueryParam.class)
+ && !param.isAnnotationPresent(Context.class))
+ return param;
+ }
+ return null;
+ }
+
+ public static ValueInfo.Origin getPostValueOrigin(Method method) {
+ var firstParam = method.getParameters()[0];
+ return firstParam.isAnnotationPresent(PathParam.class) && firstParam.getType() == Long.class
+ ? UPDATE_BODY : CREATE_BODY;
+ }
+
+ public static String getResourcePath(Class<?> resourceClass, Method method) {
+ var path = resourceClass.getAnnotation(Path.class).value();
+ var methodPath = method.getAnnotation(Path.class);
+ return methodPath != null ? path + methodPath.value() : path;
+ }
+
public static Serializable getExampleValue(Type valueType, ValueInfo.Origin origin) {
return getExampleValue(valueType, Sets.newHashSet(), origin);
}
diff --git a/server-core/src/main/java/io/onedev/server/web/page/help/ExampleProvider.java b/server-core/src/main/java/io/onedev/server/web/page/help/ExampleProvider.java
index aa45893c0a..279adc307d 100644
--- a/server-core/src/main/java/io/onedev/server/web/page/help/ExampleProvider.java
+++ b/server-core/src/main/java/io/onedev/server/web/page/help/ExampleProvider.java
@@ -9,7 +9,7 @@ import com.google.common.base.Preconditions;
import io.onedev.server.rest.annotation.Api;
import io.onedev.server.util.ReflectionUtils;
-class ExampleProvider {
+public class ExampleProvider {
private final Class<?> apiDeclaringClass;
@@ -32,4 +32,4 @@ class ExampleProvider {
}
return null;
}
-}
\ No newline at end of file
+}
diff --git a/server-core/src/main/java/io/onedev/server/web/page/help/MethodDetailPage.java b/server-core/src/main/java/io/onedev/server/web/page/help/MethodDetailPage.java
index 7d2efb0b09..9c4187c892 100644
--- a/server-core/src/main/java/io/onedev/server/web/page/help/MethodDetailPage.java
+++ b/server-core/src/main/java/io/onedev/server/web/page/help/MethodDetailPage.java
@@ -1,7 +1,5 @@
package io.onedev.server.web.page.help;
-import static io.onedev.server.web.page.help.ValueInfo.Origin.CREATE_BODY;
-import static io.onedev.server.web.page.help.ValueInfo.Origin.UPDATE_BODY;
import static io.onedev.server.web.translation.Translation._T;
import java.io.InputStream;
@@ -17,7 +15,6 @@ import java.util.regex.Matcher;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.QueryParam;
-import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.StreamingOutput;
@@ -98,14 +95,7 @@ public class MethodDetailPage extends ApiHelpPage {
@Nullable
private Parameter getRequestBodyParam() {
- for (Parameter param: getResourceMethod().getParameters()) {
- if (param.getAnnotation(PathParam.class) == null
- && param.getAnnotation(QueryParam.class) == null
- && param.getAnnotation(Context.class) == null) {
- return param;
- }
- }
- return null;
+ return ApiHelpUtils.getRequestBodyParam(getResourceMethod());
}
@Override
@@ -430,11 +420,7 @@ public class MethodDetailPage extends ApiHelpPage {
}
private ValueInfo.Origin getPostValueOrigin(Method method) {
- var firstParam = getResourceMethod().getParameters()[0];
- if (firstParam.getAnnotation(PathParam.class) != null && firstParam.getType() == Long.class)
- return UPDATE_BODY;
- else
- return CREATE_BODY;
+ return ApiHelpUtils.getPostValueOrigin(method);
}
private void appendParam(StringBuilder curlExample, String paramKey, String paramValue) {
diff --git a/server-core/src/main/java/io/onedev/server/web/page/help/ResourceDetailPage.java b/server-core/src/main/java/io/onedev/server/web/page/help/ResourceDetailPage.java
index 452c57f686..ceeb944d67 100644
--- a/server-core/src/main/java/io/onedev/server/web/page/help/ResourceDetailPage.java
+++ b/server-core/src/main/java/io/onedev/server/web/page/help/ResourceDetailPage.java
@@ -1,13 +1,8 @@
package io.onedev.server.web.page.help;
import java.lang.reflect.Method;
-import java.util.ArrayList;
import java.util.List;
-import jakarta.ws.rs.DELETE;
-import jakarta.ws.rs.GET;
-import jakarta.ws.rs.POST;
-import jakarta.ws.rs.PUT;
import jakarta.ws.rs.Path;
import org.apache.wicket.Component;
@@ -19,7 +14,6 @@ import org.apache.wicket.markup.html.panel.Fragment;
import org.apache.wicket.model.LoadableDetachableModel;
import org.apache.wicket.request.mapper.parameter.PageParameters;
-import edu.emory.mathcs.backport.java.util.Collections;
import io.onedev.server.exception.NotFoundException;
import io.onedev.server.web.component.link.ViewStateAwarePageLink;
@@ -52,19 +46,7 @@ public class ResourceDetailPage extends ApiHelpPage {
@Override
protected List<Method> load() {
- List<Method> methods = new ArrayList<>();
-
- for (Method method: resourceClass.getMethods()) {
- if (method.getAnnotation(GET.class) != null
- || method.getAnnotation(POST.class) != null
- || method.getAnnotation(DELETE.class) != null
- || method.getAnnotation(PUT.class) != null) {
- methods.add(method);
- }
- }
-
- Collections.sort(methods, new ApiComparator());
- return methods;
+ return ApiHelpUtils.getResourceMethods(resourceClass);
}
}) {
diff --git a/server-core/src/main/java/io/onedev/server/web/page/help/ResourceListPage.java b/server-core/src/main/java/io/onedev/server/web/page/help/ResourceListPage.java
index 8d3d60ce0a..b6d183d525 100644
--- a/server-core/src/main/java/io/onedev/server/web/page/help/ResourceListPage.java
+++ b/server-core/src/main/java/io/onedev/server/web/page/help/ResourceListPage.java
@@ -3,7 +3,6 @@ package io.onedev.server.web.page.help;
import static io.onedev.server.web.translation.Translation._T;
import java.util.ArrayList;
-import java.util.Comparator;
import java.util.List;
import jakarta.ws.rs.Path;
@@ -15,10 +14,7 @@ import org.apache.wicket.markup.html.list.ListItem;
import org.apache.wicket.markup.html.list.ListView;
import org.apache.wicket.model.LoadableDetachableModel;
import org.apache.wicket.request.mapper.parameter.PageParameters;
-import org.glassfish.jersey.server.ResourceConfig;
-import io.onedev.server.OneDev;
-import io.onedev.server.rest.annotation.Api;
import io.onedev.server.util.Pair;
import io.onedev.server.web.component.link.ViewStateAwarePageLink;
@@ -37,22 +33,8 @@ public class ResourceListPage extends ApiHelpPage {
@Override
protected List<Pair<Class<?>, String>> load() {
List<Pair<Class<?>, String>> pairs = new ArrayList<>();
- ResourceConfig config = OneDev.getInstance(ResourceConfig.class);
- for (Class<?> clazz: config.getClasses()) {
- if (clazz.getAnnotation(Path.class) != null) {
- Api api = clazz.getAnnotation(Api.class);
- if (api == null || !api.internal())
- pairs.add(new Pair<>(clazz, getResourceTitle(clazz)));
- }
- }
- pairs.sort(new Comparator<>() {
-
- @Override
- public int compare(Pair<Class<?>, String> o1, Pair<Class<?>, String> o2) {
- return o1.getRight().compareTo(o2.getRight());
- }
-
- });
+ for (var clazz: ApiHelpUtils.getResourceClasses())
+ pairs.add(new Pair<>(clazz, getResourceTitle(clazz)));
return pairs;
}
diff --git a/server-core/src/test/java/io/onedev/server/rest/ApiHelpJsonTest.java b/server-core/src/test/java/io/onedev/server/rest/ApiHelpJsonTest.java
new file mode 100644
index 0000000000..82cf9a23c4
--- /dev/null
+++ b/server-core/src/test/java/io/onedev/server/rest/ApiHelpJsonTest.java
@@ -0,0 +1,258 @@
+package io.onedev.server.rest;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+import java.io.InputStream;
+import java.io.Serializable;
+import java.util.Date;
+import java.util.List;
+import java.util.Set;
+
+import jakarta.persistence.ManyToOne;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.NotFoundException;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.container.ResourceInfo;
+import jakarta.ws.rs.core.Context;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.StreamingOutput;
+import jakarta.ws.rs.core.UriInfo;
+
+import org.apache.shiro.authz.UnauthenticatedException;
+import org.glassfish.jersey.server.ResourceConfig;
+import org.junit.jupiter.api.Test;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.onedev.commons.loader.AppLoader;
+import io.onedev.commons.loader.AppLoaderMocker;
+import io.onedev.commons.loader.ImplementationRegistry;
+import io.onedev.server.model.AbstractEntity;
+import io.onedev.server.model.support.administration.SecuritySetting;
+import io.onedev.server.rest.annotation.Api;
+import io.onedev.server.rest.annotation.Immutable;
+import io.onedev.server.rest.resource.ApiHelpResource;
+import io.onedev.server.security.SecurityUtils;
+import io.onedev.server.service.SettingService;
+import io.onedev.server.util.jackson.ObjectMapperProvider;
+
+public class ApiHelpJsonTest extends AppLoaderMocker {
+
+ private ObjectMapper mapper;
+
+ @Override
+ protected void setup() {
+ var registry = mock(ImplementationRegistry.class);
+ when(registry.getImplementations(Choice.class)).thenReturn(List.of(FirstChoice.class, SecondChoice.class));
+ when(AppLoader.getInstance(ImplementationRegistry.class)).thenReturn(registry);
+ mapper = new ObjectMapperProvider(Set.of(), Set.of(), registry, Set.of()).get();
+ when(AppLoader.getInstance(ObjectMapper.class)).thenReturn(mapper);
+ when(AppLoader.getInstance(ResourceConfig.class)).thenReturn(new ResourceConfig(
+ SampleResource.class, AnotherResource.class, InternalResource.class, ApiHelpResource.class));
+ }
+
+ @Override
+ protected void teardown() {
+ }
+
+ @Test
+ public void preservesHierarchyAndDoesNotExposeInternalResourcesOrJavaMethods() {
+ var help = new ApiHelpJson();
+ JsonNode index = mapper.valueToTree(help.getResources("https://onedev.example.com"));
+ assertEquals(2, index.path("resources").size());
+ assertEquals("AAA", index.at("/resources/0/title").asText());
+ assertEquals(SampleResource.class.getName(), index.at("/resources/1/id").asText());
+ assertEquals(ApiHelpJson.PATH + "/" + SampleResource.class.getName(), index.at("/resources/1/help").asText());
+ JsonNode resource = mapper.valueToTree(help.getResource(SampleResource.class));
+ assertFalse(resource.has("id"));
+ assertFalse(resource.has("help"));
+ assertEquals(ApiHelpJson.PATH + "/" + SampleResource.class.getName() + "/create", resource.at("/methods/0/help").asText());
+ assertEquals(ApiHelpJson.PATH + "/" + SampleResource.class.getName() + "/update", resource.at("/methods/1/help").asText());
+ assertEquals("Create a record", resource.at("/methods/0/title").asText());
+ assertFalse(resource.at("/methods/0").has("id"));
+ var endpoint = new ApiHelpResource(null);
+ assertThrows(NotFoundException.class, () -> endpoint.getResource(InternalResource.class.getName()));
+ assertThrows(NotFoundException.class, () -> endpoint.getResource("java.lang.System"));
+ assertThrows(NotFoundException.class, () -> endpoint.getMethod(SampleResource.class.getName(), "toString"));
+ assertThrows(NotFoundException.class, () -> endpoint.getMethod(SampleResource.class.getName(), "missing"));
+ }
+
+ @Test
+ public void matchesCreateAndUpdateBodyVisibilityAndAssociationIds() throws Exception {
+ var create = method("create", TestEntity.class);
+ var update = method("update", Long.class, TestEntity.class);
+ var created = create.at("/requestBody/example");
+ assertFalse(created.has("id"));
+ assertFalse(created.has("readOnly"));
+ assertFalse(created.has("secret"));
+ assertTrue(created.has("immutable"));
+ assertTrue(created.path("ownerId").isIntegralNumber());
+ assertFalse(created.has("owner"));
+ assertFalse(update.at("/requestBody/example").has("immutable"));
+ assertEquals("Name & description", definition(create, TestEntity.class, "CREATE_BODY")
+ .at("/properties/name/description").asText());
+ assertFalse(definition(update, TestEntity.class, "UPDATE_BODY").path("properties").has("immutable"));
+ assertTrue(update.at("/response/success/body").isNull());
+ assertEquals("Id of created test entity", create.at("/response/success/description").asText());
+ var read = method("read");
+ assertTrue(read.at("/response/success/body/example").has("id"));
+ assertTrue(read.at("/response/success/body/example").has("readOnly"));
+ }
+
+ @Test
+ public void describesParametersAndUsesCustomExamplesAndPlainDescriptions() throws Exception {
+ var detail = method("query", Long.class, String.class, List.class, int.class, UriInfo.class);
+ assertFalse(detail.has("id"));
+ assertFalse(detail.has("resource"));
+ assertFalse(detail.has("resourceDescription"));
+ assertFalse(detail.has("help"));
+ assertFalse(detail.has("curlExample"));
+ assertEquals("/~api/samples/{id}", detail.path("path").asText());
+ assertEquals(42, detail.at("/pathParameters/0/example").asInt());
+ assertEquals(3, detail.path("queryParameters").size());
+ assertTrue(detail.at("/queryParameters/0/required").asBoolean());
+ assertFalse(detail.at("/queryParameters/1/required").asBoolean());
+ assertTrue(detail.at("/queryParameters/2/required").asBoolean());
+ assertEquals("Find O'Reilly & friends", detail.at("/queryParameters/0/description").asText());
+ assertEquals("O'Reilly & friends", detail.at("/queryParameters/0/example").asText());
+ assertEquals("custom result", detail.at("/response/success/body/example").asText());
+ assertTrue(detail.path("requestBody").isNull());
+ }
+
+ @Test
+ public void documentsAllPolymorphicChoicesAndRecursiveTypes() throws Exception {
+ var detail = method("choose", Choice.class);
+ assertEquals("FirstChoice", detail.at("/requestBody/example/@type").asText());
+ var choices = definition(detail, Choice.class, "CREATE_BODY").path("oneOf");
+ assertEquals(2, choices.size());
+ assertEquals("SecondChoice", choices.at("/1/allOf/1/properties/@type/const").asText());
+ var first = definition(detail, FirstChoice.class, "CREATE_BODY");
+ assertEquals(2, first.at("/properties/mode/enum").size());
+ assertEquals("date-time", first.at("/properties/date/format").asText());
+ assertEquals("#/$defs/" + FirstChoice.class.getName() + ".CREATE_BODY", first.at("/properties/next/$ref").asText());
+ assertTrue(detail.at("/requestBody/example/next/next").isNull());
+ }
+
+ @Test
+ public void representsBinaryAndAbsentBodiesWithoutTryingToGenerateExamples() throws Exception {
+ var upload = method("upload", InputStream.class);
+ assertEquals("application/octet-stream", upload.at("/requestBody/contentType").asText());
+ assertFalse(upload.path("requestBody").has("example"));
+ assertEquals("application/octet-stream", upload.at("/response/success/body/contentType").asText());
+ assertFalse(upload.at("/response/success/body").has("example"));
+ }
+
+ @Test
+ public void keepsDocumentationAvailableWhenAnExampleProviderFails() throws Exception {
+ var detail = method("brokenExample");
+ assertTrue(detail.at("/response/success/body").has("exampleUnavailable"));
+ assertFalse(detail.at("/response/success/body").has("example"));
+ assertEquals("string", detail.at("/response/success/body/schema/type").asText());
+ }
+
+ @Test
+ public void respectsTheAnonymousAccessSettingEvenThoughHelpIsHiddenFromTheResourceList() throws Exception {
+ var settings = new SecuritySetting();
+ var settingService = mock(SettingService.class);
+ when(settingService.getSecuritySetting()).thenReturn(settings);
+ var filter = new AnonymousCheckFilter(settingService);
+ var resourceInfo = mock(ResourceInfo.class);
+ doReturn(ApiHelpResource.class).when(resourceInfo).getResourceClass();
+ var resourceField = AnonymousCheckFilter.class.getDeclaredField("resourceInfo");
+ resourceField.setAccessible(true);
+ resourceField.set(filter, resourceInfo);
+ var request = mock(HttpServletRequest.class);
+ when(request.getMethod()).thenReturn("GET");
+ var requestField = AnonymousCheckFilter.class.getDeclaredField("request");
+ requestField.setAccessible(true);
+ requestField.set(filter, request);
+ try (var security = mockStatic(SecurityUtils.class)) {
+ security.when(SecurityUtils::isAnonymous).thenReturn(true);
+ settings.setEnableAnonymousAccess(false);
+ assertThrows(UnauthenticatedException.class, () -> filter.filter(null));
+ settings.setEnableAnonymousAccess(true);
+ assertDoesNotThrow(() -> filter.filter(null));
+ settings.setEnableAnonymousAccess(false);
+ security.when(SecurityUtils::isAnonymous).thenReturn(false);
+ assertDoesNotThrow(() -> filter.filter(null));
+ }
+ }
+
+ private JsonNode method(String name, Class<?>... parameters) throws Exception {
+ return mapper.valueToTree(new ApiHelpJson().getMethod(SampleResource.class,
+ SampleResource.class.getMethod(name, parameters)));
+ }
+
+ private JsonNode definition(JsonNode detail, Class<?> type, String origin) {
+ return detail.path("$defs").path(type.getName() + "." + origin);
+ }
+
+ @Path("/samples")
+ public static class SampleResource {
+ @Api(order = 10, name = "Create a record") @POST
+ public Long create(TestEntity entity) { return null; }
+ @Api(order = 20) @POST @Path("/{id}")
+ public Response update(@PathParam("id") Long id, TestEntity entity) { return null; }
+ @GET public TestEntity read() { return null; }
+ @GET @Path("/{id}") @Api(example = "custom result")
+ public String query(@PathParam("id") @Api(example = "42") Long id,
+ @QueryParam("query") @NotEmpty @Api(description = "Find <b>O'Reilly &amp; friends</b>", example = "O'Reilly & friends") String query,
+ @QueryParam("fields") List<String> fields, @QueryParam("count") int count, @Context UriInfo uriInfo) { return null; }
+ @POST @Path("/choice") public Response choose(Choice choice) { return null; }
+ @POST @Path("/upload") public StreamingOutput upload(InputStream stream) { return null; }
+ @GET @Path("/broken") @Api(exampleProvider = "broken") public String brokenExample() { return null; }
+ public static String broken() { throw new IllegalStateException("Unavailable provider"); }
+ }
+
+ @Path("/another") @Api(name = "AAA")
+ public static class AnotherResource { @GET public String get() { return null; } }
+ @Path("/internal") @Api(internal = true)
+ public static class InternalResource { @GET public String get() { return null; } }
+
+ public static class TestEntity extends AbstractEntity {
+ private static final long serialVersionUID = 1L;
+ @Api(description = "<b>Name</b> &amp; description") private String name;
+ @Immutable private String immutable;
+ @JsonProperty(access = JsonProperty.Access.READ_ONLY) private String readOnly;
+ @JsonIgnore private String secret;
+ @ManyToOne private TestEntity owner;
+ }
+
+ public enum Mode { FIRST, SECOND }
+ public abstract static class Choice implements Serializable { private static final long serialVersionUID = 1L; }
+ public static class FirstChoice extends Choice {
+ private static final long serialVersionUID = 1L;
+ private Mode mode;
+ private Date date;
+ private FirstChoice next;
+
+ public Mode getMode() {
+ return mode;
+ }
+
+ public Date getDate() {
+ return date;
+ }
+
+ public FirstChoice getNext() {
+ return next;
+ }
+ }
+ public static class SecondChoice extends Choice {
+ private static final long serialVersionUID = 1L;
+ private String value;
+
+ public String getValue() {
+ return value;
+ }
+ }
+}