New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
New annotation proposal: ignorable objects (@ApiParam#hidden() and @ApiModel#hidden()) #1173
Comments
Update: Because of how swagger-core 1.5 now automatically includes ALL function parameters that it encounters in a resource/controller method, an annotation along the lines of the above is even more beneficial. |
Here is a repro: This method ...
... yields this
Notice how there are two body parameters. This creates an invalid swagger spec. I want swagger to completely ignore the |
@webron Let me know if the above is a sufficient repro. |
@who - it is, to an extent, but this is a different issue than the original request. The original request may be able to provide a workaround, but this should be solved in a different way if possible. Can you open a separate ticket on it? |
@who - I've added a feature in #1188 that would help overcome the specific use case you raise here (which is valid, and we should find a better way of handling it in general). Would #1188 cover your needs or can you think of other cases where |
It may also be worthwhile to add |
Not really sure how that would work. Models are scanned if they are referenced. If those are hidden, that would break the reference and the output in general. |
@who - any additional input on the |
If a class is annotated with |
Yes, but if an operation refers to it, what happens? @GET
@ApiOperation(...)
public Foo bar() {
} and @ApiModel(hidden=true)
public class Foo {
...
} What's the bar's return type in the Swagger definition? |
If you indeed wanted to I suppose one of the following would be the way to handle the logical conflict:
|
Okay, glad I managed to explain the problem I see with the example. Not always easy to communicate ideas. On the other hand, I'm not sure I see the use case you're trying to solve. Can you show me a similar case where hiding a model would affect anything? Models are scanned if they are referred to, not just randomly, so you shouldn't end up having a model that's under |
Here's one example:
Given the above, in the generated swagger spec, I would expect:
|
Also, @dilipkrish may be able to provide some rationale from the Springfox side for having class-level ignores. I think it's mainly used to ignore controllers, but he may be able to shed some light. |
Why not use http://docs.swagger.io/swagger-core/v1.5.0/apidocs/io/swagger/annotations/ApiModelProperty.html#hidden() on Would love to get @dilipkrish's input as well of course :) |
Yes, you could definitely hide at the property level, but you'd have to add that annotation any time the class is referred to across all models that use it. If you wanted an authoritative way to ensure a class is never leaked out when referred to, class-level is most assuring; it safeguards against including an unwanted model if you miss adding the annotation at the getter/field level. |
That's fair, but considering there's an alternative, and that your suggestion has a risk for the logical conflict, I'm not sure we should introduce this complexity to the library right now. |
That is understandable. I'm really mainly excited for |
Would you be okay with changing the title of the issue to |
BTW, the |
My 2 💵s The Personally I prefer to use annotations only as an aid to the api description and not as the source of truth. For e.g. if we need additional descriptive messages or if we need to infer something thats not immediately available via introspection. Having said that, it sometimes makes sense to have redundancy, where we want the annotation to be a tiebreaker or override a value like when the api developer needs to signal that they know what they are doing. Coming to this specific question, it seems weird to me to have |
@who - I believe we covered it for now. I don't think we should have the |
work-arounds described in the thread. |
for people who still confused after finish reading the thread. to hidden params in controller function @ApiOperation("设备更新")
@PostMapping("/update")
@ApiImplicitParams({
@ApiImplicitParam(name = "dType", dataType = "DeviceType", paramType = "query", value = "设备类型", required=true),
@ApiImplicitParam(name = "dNo", dataType = "string", paramType = "query", value = "设备号", required=true),
@ApiImplicitParam(name = "dVer", dataType = "string", paramType = "query", value = "版本", required=true),
@ApiImplicitParam(name = "simNo", dataType = "string", paramType = "query", value = "sim卡号", required=true),
@ApiImplicitParam(name = "cardNo", dataType = "string", paramType = "query", value = "安全芯片号", required=true),
@ApiImplicitParam(name = "dStatus", dataType = "DeviceStatus", paramType = "query", value = "设备状态", required=true),
@ApiImplicitParam(name = "dDesc", dataType = "string", paramType = "query", value = "设备备注", required=true)
})
public ApiResponse updateById(Long id,@ApiIgnore @ApiParam(hidden = true) Device device) {
Device beforeUpdate = deviceRepository.findOne(id);
device.setCreateDate(beforeUpdate.getCreateDate());
device.setUpdateDate(System.currentTimeMillis()/1000);
Device ret = deviceRepository.saveAndFlush(device);
return RestResponseGenerator.genSuccess(ret, "更新设备"+id+"成功");
}
|
Springfox has a really convenient way of excluding things from being included by swagger's parsing stack. [ See https://github.com/springfox/springfox/blob/master/springfox-core/src/main/java/springfox/documentation/annotations/ApiIgnore.java ]
This is very useful, and I would like to recommend that something to this effect be included in the Swagger core annotation libraries.
The text was updated successfully, but these errors were encountered: