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.javaindex 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;@Providerpublic class AnonymousCheckFilter implements ContainerRequestFilter {@@ -37,7 +38,9 @@ public class AnonymousCheckFilter implements ContainerRequestFilter {@Overridepublic 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.javanew file mode 100644index 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.javanew file mode 100644index 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.htmlindex 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.javaindex 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));+ }+@Overrideprotected 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);}-+@Nullableprotected 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);}@Nullableprotected 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);}@Overridediff --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.javaindex 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.javaindex 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.javaindex 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 {@Nullableprivate 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.javaindex 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 {@Overrideprotected 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.javaindex 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 {@Overrideprotected 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.javanew file mode 100644index 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 & 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> & 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;+ }+ }+}