Hi David,
I could use some guidance here actually on whether to keep the @Parameter annotation. The plan was to deprecate it, but I'm willing to keep it in.
The "new" approach is to annotate your parameters on the method arguments like so:
@RestMethod(name="GET",
path="/foo/{somePathParam}/*",
properties ={
@Property(name=HTMLDOC_header, value="$L{title}")
}
)
public ServiceResult someMethod(
RestRequest request,
RestResponse response,
@Path(
name="somePathParam",
description="xxx"
)
String somePathParam) {
...
}
The @MethodSwagger(parameters) annotation is thus really not needed anymore, but the Simplified-JSON syntax for defining it is provided as a free-form way of doing so. The @Parameter annotation didn't include all possible Swagger values, so this was a way to "keep up with the spec" if you wanted to define the parameters in the @MethodSwagger like so:
@RestMethod(name="GET",
swagger=@MethodSwagger(
parameters={
"{name:'somePathParam',in:'path',description:'xxx'}"
}
)
)
However, parameters defined like this are considered "documentation only", meaning you don't get auto-validation of parameter values. That's actually part of the design because it allows you to provide either validating or non-validating Swagger. For example,
// Validating
@Path(
name="somePathParam",
description="xxx",
minLength=10, maxLength=20
)
// Non-validating
@RestMethod(name="GET",
swagger=@MethodSwagger(
parameters={
"{name:'somePathParam',in:'path',description:'xxx',minLength:10,maxLength:20}"
}
)
)
As far as keeping @Parameter, I could re-add it using a separate "parameters2" attribute like so:
@RestMethod(name="GET",
swagger=@MethodSwagger(
parameters2={
My concerns with that though are that we're defining two separate ways of defining free-form parameters. And the existing @Parameter annotation didn't get the Swagger spec exactly correct (it was an amalgam of "body" and the other parameter types which only has some overlap in Swagger).
I'm not sure why you're seeing that "@Path used without name or value" error. I'll see if I can reproduce that. The workaround is to add the name of your path parameter like so:
public ServiceResult someMethod(
RestRequest request,
RestResponse response,
@Path("somePathParam") String somePathParam) {
...
}