Contributions
One Endpoint, multiple examples/Responses? (Java Annotations)
Hey, I'm using Swagger to document my Java API. This is using a Jersey resources/Jackson JSON objects and I want to document it using annotations in the code. The 3 swagger libraries I'm using are: swagger-core, swagger-jaxrs2, swagger-models. The issue I keep running into is that I sometimes want to document different implementations for an endpoint but I'm not sure how to go about it. To give a straigthforward example, I have the endpoint "/login" which takes the Jackson/POJO object "LoginAuthJson". The issue is that in this case a login can be initiated either by a Facebook user (where the object will contain a facebook ID and a token from facebook), or it can be a login from a registered email user (in which case the body contains an email and a password.). So I want to somehow be able to show example bodies for both facebook and email login separately. Any suggestion on how I can do something like this? Edit: so I have gotten the schema to work sort of like I Want using oneOf, but that doesn't seem to work for examples 😞632Views0likes0CommentsVaried Example Values from same Model (Java)
Hey, I have two (somewhat related) situations where I would love some input on how to best approach this. I am using the swagger-core java library and doing all of this with annotations to my code. 1) I am aiming for an API response which has an Outside wrapper with the status, and a result document with the key for the specific document you are fetching (example here: https://medium.com/@shazow/how-i-design-json-api-responses-71900f00f2db ). One problem I have encountered here is that if I have 1 "ResultWrapper" model which has one "Result" model, it would (in examples and the model) always display all possible results. So what I have ended up doing is created A Wrapper and a Result model for each possible result (f.ex a UserWrapper and userResult) which just extend the Abstract result wrapper and adds the User specific fields: https://www.dropbox.com/s/tsumo4sz8iot8b5/Screenshot%202020-04-21%2012.56.44.png?raw=1 2) In a similar vein, I have defined the "example" values over the relevant fields (so for examle inside the User result model). The problem I'm having here is that it always returns all the fields as example values. For example one request I have (which would still use the User model), only returns an ID and activation status, but because I just define the User model as the response, it uses the example values of that field. The one way I can see to tackle this is to create extensions of the models with different example values, descriptions etc. But that then comes with the problem that the bottom "Models" section has a ton of duplicated models, because each User response would have its own model (this is already kind of happening where each result has 3 different models because of the nested nature.) Any input on how to best approach this? I guess to summarise I want to use the same underlying models for a lot of different operations (POST and responses), but use different example values for the different requests, and I want to avoid bloating (specifically the Model section) with endless configurations of the same model.577Views0likes0Comments