From 0c73a9c7e6b2545bd3d9b62d93d35fa90c8fa5eb Mon Sep 17 00:00:00 2001 From: Nickolas Da Silva Date: Fri, 18 Apr 2025 06:51:05 +0200 Subject: [PATCH 1/2] feat(core) add @SegmentParameter annotation Services like refind use the {segment} path parameter often don't document them. This makes for a broken openapi specs that fails validation of some code generation tools. This commit adds a `@SegmentParameter` annotation to make it easier for restler-core dependants to fix their broken openapi specs. --- .../restdsl/annotations/SegmentParameter.java | 26 +++++++++++++++++++ .../resources/BaseServiceResource.java | 5 ++-- 2 files changed, 29 insertions(+), 2 deletions(-) create mode 100644 restler-core/src/main/java/net/researchgate/restdsl/annotations/SegmentParameter.java diff --git a/restler-core/src/main/java/net/researchgate/restdsl/annotations/SegmentParameter.java b/restler-core/src/main/java/net/researchgate/restdsl/annotations/SegmentParameter.java new file mode 100644 index 0000000..26a7c3b --- /dev/null +++ b/restler-core/src/main/java/net/researchgate/restdsl/annotations/SegmentParameter.java @@ -0,0 +1,26 @@ +package net.researchgate.restdsl.annotations; + +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.enums.ParameterIn; +import io.swagger.v3.oas.annotations.media.Schema; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD}) +@Retention(RetentionPolicy.RUNTIME) +@Parameter( + name = "segment", + in = ParameterIn.PATH, + schema = @Schema(type = "string", example = "-"), + description = "A rest-dsl query, See https://github.com/researchgate/restler#get", + required = true +) +public @interface SegmentParameter { + String name() default "segment"; + String description() default "A rest-dsl query, See https://github.com/researchgate/restler#get"; + ParameterIn in() default ParameterIn.PATH; + boolean required() default true; +} diff --git a/restler-core/src/main/java/net/researchgate/restdsl/resources/BaseServiceResource.java b/restler-core/src/main/java/net/researchgate/restdsl/resources/BaseServiceResource.java index bd5d7b5..36522fc 100644 --- a/restler-core/src/main/java/net/researchgate/restdsl/resources/BaseServiceResource.java +++ b/restler-core/src/main/java/net/researchgate/restdsl/resources/BaseServiceResource.java @@ -4,6 +4,7 @@ import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.enums.ParameterIn; import io.swagger.v3.oas.annotations.media.Schema; +import net.researchgate.restdsl.annotations.SegmentParameter; import net.researchgate.restdsl.domain.EntityInfo; import net.researchgate.restdsl.exceptions.RestDslException; import net.researchgate.restdsl.model.BaseServiceModel; @@ -68,7 +69,7 @@ public BaseServiceResource(BaseServiceModel serviceModel) throws RestDslEx } @Operation(summary = "Retrieve entities using the generic researchgate 'restler' query-language: https://github.com/researchgate/restler#get") - @Parameter(name = "segment", in = ParameterIn.PATH, schema = @Schema(type = "string", example = "-"), description = "A rest-dsl query, See https://github.com/researchgate/restler#get") + @SegmentParameter @Parameter(name = "fields", in = ParameterIn.QUERY, description = "Only return this list of comma-separated fields. Use '*' to return all", example = "*") @Parameter(name = "limit", in = ParameterIn.QUERY, schema = @Schema(type = "integer", format = "int32"), description = "Limit the number of returned records") @Parameter(name = "offset", in = ParameterIn.QUERY, schema = @Schema(type = "integer", format = "int32"), description = "Skip this many records. Use this together with limit to implement pagination.") @@ -84,7 +85,7 @@ public EntityResult getEntityResult(@PathParam("segment") PathSegment segment } @Operation(summary = "Returns a human readable description of the generated database operations. This is intended for client to develop and debug rest-dsl queries") - @Parameter(name = "segment", in = ParameterIn.PATH, schema = @Schema(type = "string", example = "-"), description = "A rest-dsl query, See https://github.com/researchgate/restler#get") + @SegmentParameter @Parameter(name = "fields", in = ParameterIn.QUERY, description = "Only return this list of comma-separated fields. Use '*' to return all", example = "*") @Parameter(name = "limit", in = ParameterIn.QUERY, schema = @Schema(type = "integer", format = "int32"), description = "Limit the number of returned records") @Parameter(name = "offset", in = ParameterIn.QUERY, schema = @Schema(type = "integer", format = "int32"), description = "Skip this many records. Use this together with limit to implement pagination.") From 8b66474e88ff3108d981e842c4ffa5a0e1fef8c0 Mon Sep 17 00:00:00 2001 From: Nickolas Da Silva Date: Fri, 18 Apr 2025 07:07:31 +0200 Subject: [PATCH 2/2] fix(SegmentParameter) default required=false --- .../researchgate/restdsl/annotations/SegmentParameter.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/restler-core/src/main/java/net/researchgate/restdsl/annotations/SegmentParameter.java b/restler-core/src/main/java/net/researchgate/restdsl/annotations/SegmentParameter.java index 26a7c3b..c9db891 100644 --- a/restler-core/src/main/java/net/researchgate/restdsl/annotations/SegmentParameter.java +++ b/restler-core/src/main/java/net/researchgate/restdsl/annotations/SegmentParameter.java @@ -16,11 +16,11 @@ in = ParameterIn.PATH, schema = @Schema(type = "string", example = "-"), description = "A rest-dsl query, See https://github.com/researchgate/restler#get", - required = true + required = false ) public @interface SegmentParameter { String name() default "segment"; String description() default "A rest-dsl query, See https://github.com/researchgate/restler#get"; ParameterIn in() default ParameterIn.PATH; - boolean required() default true; + boolean required() default false; }