Add sample request/response objects to rest apis

[Hema Bhatia]

Hi,

I recently shifted from wadl to swagger. All looks pretty good, except I could not find a way to add sample requests and responses (JSON and XML) to the rest apis.

In wadl , there is RepresentationDocType under com.sun.jersey.server.wadl.generators.resourcedoc.model which allows to append example body to api. Not sure, what the best way to do the same thing in Swagger.

Could anyone help me out with this? 

Thanks,

Hema

[Ron]

Do you have a sample of the output you'd get from RepresentationDocType?

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

[Hema Bhatia]

We create custom doc using resourceDoc class, and show the resources in /docs path. Each resource has its own page with details. Swagger simplified a lot of things for us, except inablity to show sample request/reponse is being a show-stopper.

Sample from old docs: The block of code part below was generated by appending to resourceDoc class (http://grepcode.com/file/repo1.maven.org/maven2/com.sun.jersey/jersey-bundle/1.1.5/com/sun/jersey/server/wadl/generators/resourcedoc/model/RepresentationDocType.java)

Sample Request

http://localhost:8080/pubsub-service/subscribe

Content Type: application/json

Content Type: application/xml

Sample Response

Response Code: 200

{
  "topic" : "testTopic1",
  "endpoint" : "http://example.com/endpoint",
  "fromStart" : true
}

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

[Ron]

Okay, Swagger does not directly have a way to include input/output samples. I admit I never thought of it being required as it does tell you what to expect in terms of model description.

In fact, if you look at the Swagger-UI, I believe you see the models quite clearly - for example:

However, if you do want to include it in the description in some way, you may want to use the "notes" field of the operation which you can find here - https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#operationNotes

It's not specific for input/output, but it's currently the most appropriate field.

If you think this is a feature you'd like to see in a future version of Swagger, please feel free to open an issue on the swagger-spec repo with an elaborate explanation and hopefully some samples.

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

[Hema Bhatia]

Thanks for the quick response Ron. Yes, I plan to use notes only, if all other options are closed. 

Another thing was can't I just write another annotation for @ApiExample? How easy/difficult would it be?

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

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

[Ron]

You can, but I wouldn't. That would go outside the spec and may break any third party tools that automatically analyze the output of swagger.

I believe the right approach would be to evolve the spec.

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

[tony tam]

If your goal is to show examples in swagger UI I suggest we argument the models in swagger js. Then you don't need to modify the source

There is an existing request to do this, it's my recommended approach

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

[Hema Bhatia]

Thanks Tony.

Could you point us to the link where the request is made. I could not find it in specs.

[Hema Bhatia]

I saw the swagger js project. I could not get any idea on how can we change the model in swagger js? Could you elaborate, or point me to some examples?

On Tuesday, April 1, 2014 10:13:01 AM UTC-7, tony tam wrote:

[Ron]

Jan just opened an issue regarding the samples - https://github.com/wordnik/swagger-spec/issues/39
Feel free to jump in and voice your opinion.

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

[Allen Dean]

I see that  issue 39 is closed and that examples are in version 2.0. But I can't find any mention of the example requests. Can someone point me to how and where those are annotated?

Thanks

[Ron]

Are you talking about the spec or a specific tool?

[Allen Dean]

Just the spec. I see examples field for the response object (Example object)  but don't see the examples for requests. What am I missing

[Ron]

Right, there are no request examples. We decided not to include those as they will tend to lead to documentation rot over time, since they need to be manually maintained.

They could be auto-generated by the tools though.

[Allen Dean]

Thanks for the details. 

I did try out the response examples in the editor and couldn't get them to display. I suspect that part of the preview is not enabled since I'm not getting an error in the YAML.

[Ron]

It's quite possible there are still parts that are not implemented in the editor and in the ui. Feel free to open issues on the respective project as you encounter those missing features.

--

[yangs...@gmail.com]

May I know is there any support in Spring boot for swagger example response value ? thanks very much.

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

[Ron Ratovsky]

Assuming you’re using Springfox, you’d need to ask them in their repository.

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.

 

--

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.