Multiple messages for the same http status code not displayed.

[kr]

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,

[Ron Ratovsky]

You can't describe multiple messages for a single http status code. That's not supported by the spec.

--
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 swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

[kr]

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 <kavit...@gmail.com> 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,

-- 

[Ron Ratovsky]

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.

--

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 swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Adam Moliski]

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"

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Ron Ratovsky]

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

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

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 swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Adam Moliski]

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...)

            

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 swagger-swaggers...@googlegroups.com.

[amit upadhyay]

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

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

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 swagger-swaggersocket+unsub...@googlegroups.com.

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 swagger-swaggersocket+unsub...@googlegroups.com.