Hello, I am new in swagger i just gone through the post and not clear with how I will use one @ApiResponse status code with different different descriptions,
I have to do it for example @ApiResponse(code = 200, message = "Returns a list"), @ApiResponse(code = 400, message = "At least 1 click through URL must be specified "), @ApiResponse(code = 400, message = "Buyer creative id not specified"), @ApiResponse(code = 400, message = "Creative height not specified") }) How would i do that as of now its allowing me one one code and one descriptions. Please help if possible Thanks Amit On Friday, June 5, 2015 at 5:23:25 AM UTC+5:30, Adam Moliski wrote: > > Yes, it was very informative. Thanks for taking the time to write up such > a thorough response! > > If I get some free time, I'll take a shot at making the editor show an > overloaded-key warning and submit a pull request, I'm actually a bit > surprised that an overloaded key error isn't thrown by the parser library > the editor is using. > > > I was originally going to suggest an array of sub-errors that can be > placed under each error to avoid the name-collision issue from key|value > mapping. However, now now that I think about it, my only goal was to make > the entry more human-readable, I definitely agree that it needs to be > machine friendly, so multiple responses to an error code could cause > problems. The human readable goal can be achieved by just putting a table > in the description, like > > responses: > 200: > description: State changed successfully > 404: > description: Device with the specified name not found, > Simulation with the specified name not found > schema: > $ref: '#/definitions/Error' > 400: > description: | > > Error | Cause > :--|:-- > Action parameter missing| An action must be specified for the > Device > Unknown Action| The action given in the 'action' argument is > not valid. > Invalid Transition| Action must be valid for the current state > of the Device, see the table above for valid actions > > schema: > $ref: '#/definitions/Error' > > That way, the returned schema is the same, but more information can be > cleanly given about the each error 'type' that can be found in the returned > error object. > > Now my only issue is finding a Swagger viewer that displays the markdown > tables (submitted a topic about this, but it may be stuck in a pending > moderation queue...) > > > On Thu, Jun 4, 2015 at 7:33 PM, Ron Ratovsky <[email protected] > <javascript:>> wrote: > >> You're raising several issues here, so let's tackle those one by one. >> >> First, the editor - if try adding more than one response for a status >> code, you'll see that only the last one renders in the right preview pane. >> This is a *technical* limitation well beyond our capabilities - that's >> just how JSON parsers work. Since you can't have multiple keys with the >> same name, one definition will override the others. I'm not 100% if it is >> well-defined which one takes over or whether it's the parser's choice, but >> it's definitely defined as only one remaining. >> However, the editor, being a designer tool, should give you a warning as >> a user to let you know that you're doing that. It's probably not easy to do >> so because of the automatic behavior of the parser, but let's leave that as >> a challenge to the editor's developers. For this, I'd ask you to open an >> issue on the project, and you can ever add a reference to this comment. >> >> Now, let's go over about why it is 'not supported' (and you'll understand >> why I use the quotes). One of the challenges (or goals) of the Swagger >> specifications is that it reaches out to two consumer types - humans and >> computers. Even in its pure form (be it YAML or JSON), a Swagger definition >> is readable by humans as it has a fairly simple and clean structure (or so >> we hope). >> Normally, when you think about status code responses (and I'm happy to >> hear that you opt to use those as intended), you know that these codes have >> a specific meaning. Not everyone uses the codes 'properly' (like sending >> 201 for a successful POST operation), but that is indeed up to the API >> designer. >> Now, there are certainly cases that a given code can be sent for multiple >> reasons, where it may be even more common for 4XX and 5XX codes. >> >> Let's take a look at the example provided by the OP - for code 400, there >> are the following descriptions: >> >> 1. NGP-GEN-0000: When Unknown exception occurred >> 2. NGP-GEN-0104: When Provided UserToken is not valid >> 3. NGP-GEN-0105: Invalid session id >> 4. NGP-GEN-1007: When Access signature is not allowed by IA >> 5. NGP-GEN-1009: When voyager system is not available >> >> 5 possible reasons to get 400. As *descriptions*, those offer no value >> to computers as consumers. A machine will get the 400 and will parse only >> that. The description is only meta data for the 400 which is not part of >> the response (as in, it is part of the Swagger description). For humans, >> that information could be useful, but it doesn't require multiple >> definitions. You can simple have a string with new lines (even use GFM) and >> have a full document there if you need to describe a whole set of reasons >> to get that error. >> >> When *does* it matter? When the *response* changes. So let's say that >> description is not only used for documentation purposes, but also that's >> the actual possible returned value. If that's the case, I'd argue the >> documentation in this case is lacking. You would want to say the return >> type is a string, and limit the options using an enum to the descriptions >> as provided. In that case, again, you don't need multiple occurrences of >> the status code. If I'll go slightly beyond the scope of Swagger, I'd also >> say that the response shouldn't be a string at all but rather a parsable >> structure (be it JSON, XML, YAML) separating the error code from the >> description. That would make it easier for machines to parse and process >> and would also be easier to document. You'll probably agree with me that >> it'd be much more difficult to create a generated client from a Swagger >> definition that needs to parse an error string to get out the error code >> and process it, than to simply process a specific field with known possible >> values. >> >> However, even with everything that's said above, we may have certainly >> missed possible use cases where there would be a good strong reason as to >> why to allow multiple descriptions of a single response code. This is not >> about making demands from your end, but rather expressing your needs which >> may apply to others as well. If you feel strongly about it, you're more >> than welcome to open an issue on swagger-spec with your reasoning and we >> will consider it for a future version of the spec, depending on other >> users' feedback on it. >> >> Hope you found it informative, >> >> Ron >> >> On Thu, Jun 4, 2015 at 6:57 PM, Adam Moliski <[email protected] >> <javascript:>> wrote: >> >>> I understand the technical reasoning for this, but I'd like to add that >>> the single description thing caused a bit of frustration for me as well. I >>> didn't realize that duplicates were being clobbered until after I was >>> bitten by someone asking me why they got an error that wasn't mentioned in >>> the docs. If you are 100% opposed to having duplicates, the editor should >>> throw up a warning if someone does accidentally have a duplicate. >>> >>> Though I'm in no place to make a demand, I would really like to see the >>> ability to show multiple errors cleanly. A 500 error could have multiple >>> causes, for example, so my 500 errors usually end up being really long with >>> "A OR B OR C OR D happened, look at the message field of the response for >>> more details" >>> >>> On Thursday, June 4, 2015 at 4:35:19 PM UTC-4, Ron wrote: >>>> >>>> So here's the thing - multiple responses per code were never allowed in >>>> Swagger. >>>> >>>> However, in Swagger 1.2 and earlier, the structure of the responses did >>>> not impose this restriction, so while it was not allowed, people could >>>> still document it that way. >>>> >>>> In Swagger 2.0 the structure has changed and now imposes a single >>>> description per HTTP response. >>>> >>>> What you *can* do is have a single 400 response code description >>>> describing the multiple options. >>>> >>>> On Thu, Jun 4, 2015 at 4:24 PM, kr <[email protected]> wrote: >>>> >>>>> HI Ron, >>>>> Thanks for your quick response. But, I know a team that has done this >>>>> and provided the pdf version of swagger but i don't have the complete >>>>> source code. They defined the annotations in an interface and used >>>>> multiple @ApiResponse for same http status code and different sub code. >>>>> Please see the code Snippet attached. I tried the same thing with a class >>>>> and also an interface and it did not work. Please let me know if you have >>>>> any ideas. >>>>> >>>>> Thanks! >>>>> >>>>> >>>>> >>>>> On Thursday, June 4, 2015 at 4:03:47 PM UTC-4, Ron wrote: >>>>>> >>>>>> You can't describe multiple messages for a single http status code. >>>>>> That's not supported by the spec. >>>>>> >>>>>> On Thu, Jun 4, 2015 at 4:01 PM, kr <[email protected]> wrote: >>>>>> >>>>>>> I was able to generate swagger API documentation for my restful >>>>>>> services that use Jboss and resteasy. The only issue i am facing is in >>>>>>> generating multiple messages for http status codes. For eg : For http >>>>>>> status code 400, i would like to have more than one entry with some sub >>>>>>> codes. Please see my code snippet below: >>>>>>> @ApiResponses({ >>>>>>> @ApiResponse(code = 200, message = "2001: >>>>>>> IFX_ArrangementsEligibility service timeout"), >>>>>>> @ApiResponse(code = 400, message = "2002: Non zero status code"), >>>>>>> @ApiResponse(code = 400, message = "2003: Not found") >>>>>>> }) >>>>>>> In the above snippet, only the code 200 and code 400 -message 2003 >>>>>>> comes up but not code 400 - message 2002. Kindly help. Apparently it >>>>>>> picks >>>>>>> up only last one defined, which is sub code 2003 here. I am attaching >>>>>>> web.xml and the main service class that defines my resources that has >>>>>>> annotations. >>>>>>> >>>>>>> Thanks, >>>>>>> >>>>>>> -- >>>>>>> >>>>>> >>>>>> >>>>>> -- >>>>>> ----------------------------------------- >>>>>> http://swagger.io >>>>>> https://twitter.com/SwaggerApi >>>>>> ----------------------------------------- >>>>>> >>>>> -- >>>>> You received this message because you are subscribed to the Google >>>>> Groups "Swagger" group. >>>>> To unsubscribe from this group and stop receiving emails from it, send >>>>> an email to [email protected]. >>>>> For more options, visit https://groups.google.com/d/optout. >>>>> >>>> >>>> >>>> >>>> -- >>>> ----------------------------------------- >>>> http://swagger.io >>>> https://twitter.com/SwaggerApi >>>> ----------------------------------------- >>>> >>> -- >>> You received this message because you are subscribed to the Google >>> Groups "Swagger" group. >>> To unsubscribe from this group and stop receiving emails from it, send >>> an email to [email protected] >>> <javascript:>. >>> For more options, visit https://groups.google.com/d/optout. >>> >> >> >> >> -- >> ----------------------------------------- >> http://swagger.io >> https://twitter.com/SwaggerApi >> ----------------------------------------- >> >> -- >> You received this message because you are subscribed to a topic in the >> Google Groups "Swagger" group. >> To unsubscribe from this topic, visit >> https://groups.google.com/d/topic/swagger-swaggersocket/KAmdyf4aRGs/unsubscribe >> . >> To unsubscribe from this group and all its topics, send an email to >> [email protected] <javascript:>. >> For more options, visit https://groups.google.com/d/optout. >> > > -- You received this message because you are subscribed to the Google Groups "Swagger" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
